> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bellows.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure your repo

> .bellows.yaml sets where the agent works and what “done” means.

## Minimal file

```yaml .bellows.yaml theme={null}
environment:
    image: golang:1.25
```

Only `image` is required. Without gates, though, nothing checks the agent's work, so add at least one.

## Full example

```yaml Go theme={null}
environment:
    image: golang:1.25
    # env vars whose directories persist between runs
    cache:
        - GOCACHE
        - GOMODCACHE
    setup: "go mod download && make tools"
    gates:
        - name: build
          command: "make build"
          # timeout is in minutes
          timeout: 5
        - name: test
          command: "make test"
          timeout: 10
        - name: lint
          command: "make lint"
          timeout: 10
        - name: test-filter
          command: 'go test -race -count=1 -run "$GATE_FILTER" ./...'
          # the agent runs it while working and picks $GATE_FILTER
          on_demand: true
          filter: true
```

```yaml Node theme={null}
environment:
    image: node:22
    cache:
        - npm_config_cache
    setup: "npm ci"
    gates:
        - name: typecheck
          command: "npm run typecheck"
          timeout: 5
        - name: test
          command: "npm test"
          timeout: 15
```

```yaml Python theme={null}
environment:
    image: python:3.13
    cache:
        - PIP_CACHE_DIR
    setup: "pip install -e '.[dev]'"
    gates:
        - name: test
          command: "pytest -q"
          timeout: 15
```

## Fields

| Field | Required | Description |
| - | - | - |
| `image` | yes | Docker image the runner starts from, by tag (`golang:1.25`). Digests (`@sha256:…`) are refused |
| `setup` | no | Shell command run before the agent starts; retried while it fails. Max 4096 chars |
| `cache` | no | Up to 16 env var names whose directories persist between runs |
| `gates` | no | Up to 16 checks; see below |

> [!NOTE]
>
> The file can also declare `services` (sidecars such as Postgres), `policy` and `reviewers`. See [Services](https://docs.bellows.cloud/guides/services.md) and [Policy and reviewers](https://docs.bellows.cloud/guides/policy-and-reviewers.md).

## Gate options

How gates run, fail and get repaired: [Gates](https://docs.bellows.cloud/guides/gates.md). Env vars and secrets for `setup` and gates: [Environment variables and secrets](https://docs.bellows.cloud/guides/env-and-secrets.md).

| Key | Description |
| - | - |
| `name` | Up to 64 chars; shown in the task's Verification panel |
| `command` | One line, up to 4096 chars |
| `timeout` | Whole minutes, 1–120 |
| `on_demand` | `true`: the agent can run it while working, and the end-of-run gate pass skips it |
| `filter` | `true`: the agent can narrow the run; the value arrives as `$GATE_FILTER` |

## Common errors

> [!WARNING]
>
> **Strict parser.** Unknown keys and tab characters are errors, and the error names the line. Indent with spaces. Put comments on their own line: a `#` after a value is read as part of the value.

> [accordion] Task fails with “config” before the agent starts
>
> The file didn't parse. Open the failed job: the error names the line and the key. Fix it on the default branch, then retry the task.

> [accordion] Setup keeps retrying
>
> `setup` is retried while it fails. Run the same command locally inside the same image, e.g. `docker run --rm -it golang:1.25 sh`.

> [accordion] Gate times out
>
> Raise `timeout` (max 120), or split the gate. Slow suites fit better as an `on_demand` gate plus a fast default gate.

Every key, limit and default: [.bellows.yaml reference](https://docs.bellows.cloud/reference/bellows-yaml.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.