> For the complete documentation index, see [llms.txt](https://no0dles.gitbook.io/hammerkit/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://no0dles.gitbook.io/hammerkit/task/needs.md).

# Needs

`needs` connect a task to the [services](/hammerkit/service.md) it depends on — a database, a queue, an API. When you run a task, hammerkit starts every service it needs, waits until each is ready, runs the task, and stops the services again once nothing else needs them.

```yaml
services:
  postgres:
    image: postgres:16-alpine
    healthcheck:
      cmd: "pg_isready -U postgres"
    ports:
      - 5432

tasks:
  api:
    description: "start api"
    image: node:24-alpine
    needs: [postgres]
    cmds:
      - node index.js
```

## Readiness

If a service defines a [`healthcheck`](/hammerkit/service/container.md#healthcheck), hammerkit runs that command inside the service container and only starts the dependent task once it exits `0`. The check is polled about once a second until it passes; there are no `interval`/`timeout`/`retries` knobs — `cmd` is the only field. A check that never passes simply keeps the dependent task waiting until you cancel the run, so make the command something that genuinely reports readiness (like `pg_isready`).

Without a healthcheck the task may start the moment the container starts, before the service inside it is actually accepting connections.

## Connecting to the service

How a task reaches its service depends on whether the task runs in a container:

* **Container task** (has an `image`): it shares a network with the service and reaches it by the **service name** as the hostname, on the service's **container port**. For the example above, connect to `postgres:5432`.
* **Local task** (no `image`): it isn't on that network, so hammerkit injects the connection details as environment variables instead — `HAMMERKIT_POSTGRES_HOST` and `HAMMERKIT_POSTGRES_PORT`. See [environment hints for local tasks](/hammerkit/service.md#environment-hints-for-local-tasks).

A robust pattern that works for both is to keep the connection in a shared top-level `envs` block and reference it from the service and the task:

{% code title=".hammerkit.yaml" %}

```yaml
envs:
  POSTGRES_USER: api
  POSTGRES_DB: api
  DATABASE_URL: postgres://api@postgres:5432/api

services:
  postgres:
    image: postgres:16-alpine
    envs:
      POSTGRES_USER: api
      POSTGRES_DB: api
      POSTGRES_HOST_AUTH_METHOD: trust
    healthcheck:
      cmd: "pg_isready -U api"
    ports:
      - 5432

tasks:
  migrate:
    image: node:24-alpine
    needs: [postgres]
    envs:
      DATABASE_URL: $DATABASE_URL
    cmds:
      - node migrate.js
```

{% endcode %}

## Naming a need

A bare `needs: [postgres]` uses the service under its own name. To depend on a service under a different local alias — handy when a referenced/included file exposes it under a prefix — use the object form:

```yaml
tasks:
  api:
    image: node:24-alpine
    needs:
      - service: db:postgres   # the service to depend on
        name: postgres         # the hostname/alias the task uses
    cmds:
      - node index.js
```

See [services](/hammerkit/service.md) for defining services, lifecycle and the [connection-string details](/hammerkit/service.md#environment-hints-for-local-tasks).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://no0dles.gitbook.io/hammerkit/task/needs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.