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

# config.toml

> Every .amika/config.toml key at a glance.

`.amika/config.toml` lives at the root of a Git repository and declares rig
defaults for that repository. This page is a compact lookup of every key.

> [!NOTE]
>
> For concepts, examples, validation rules, and merge semantics, see the full
> guides:
> [How configuration works](https://docs.amika.dev/guides/configuration.md) (precedence, multi-repo,
> repo-less) and the
> [config.toml reference](https://docs.amika.dev/guides/config-toml.md) (field-by-field spec).

> [!NOTE]
>
> The hosted platform also accepts the singular `[service.<name>]` as an alias
> for `[services.<name>]`.

## `[lifecycle]`

Setup and start scripts. See [details](https://docs.amika.dev/guides/config-toml.md#lifecycle).

| Key | Type | Default | Summary |
| - | - | - | - |
| `setup_script` | string (path) | no-op | Script run once during initial creation. Overridable with `--setup-script`. |
| `start_script` | string (path) | no-op | Script run each time a stopped rig is restarted (hosted only). |

## `[env]`

Environment variables set inside the rig. See
[details](https://docs.amika.dev/guides/config-toml.md#env) and
[env vars vs. secrets](https://docs.amika.dev/guides/env-vars-and-secrets.md).

| Value form | Syntax | Summary |
| - | - | - |
| Plain string | `KEY = "value"` | Set as-is. |
| Secret reference | `KEY = { secret = "name" }` | Resolved from the vault at create time. |
| Service reference | `KEY = { service = "name", field = "url" \| "host" \| "port" }` | Injects a service's URL, host, or port. |

Names must be `UPPER_SNAKE_CASE`. DB entries override TOML entries per key.

## `[services.<name>]`

Named services with port bindings. See [details](https://docs.amika.dev/guides/config-toml.md#services)
and [Services](https://docs.amika.dev/reference/services.md).

| Key | Type | Summary |
| - | - | - |
| `port` | integer or `"port/protocol"` | Single port (mutually exclusive with `ports`). |
| `ports` | array of integer or `"port/protocol"` | Multiple ports (mutually exclusive with `port`). |
| `url_scheme` | `"http"` / `"https"`, or array of `{ port, scheme }` | URL generation. Multi-port services must use the array form. |

Ports 60899–60999 are reserved. Service definitions are DB-wins-all.

## `[sandbox]`

Default rig settings. See [details](https://docs.amika.dev/guides/config-toml.md#sandbox).

| Key | Type | Default | Values |
| - | - | - | - |
| `preset` | string | `"coder"` | `"coder"`, `"coder-plus-docker"` |
| `size` | string | provider's `m` tier (`a0.m`, or `a1.medium` on E2B) | A versioned size offered by the provider, or a friendly alias. See [sizes](https://docs.amika.dev/guides/config-toml.md#size). |
| `snapshot` | string | none | Friendly snapshot label (not the org-qualified name). |

## `[filesystem]`

Additional repos to clone alongside the primary repo. See
[details](https://docs.amika.dev/guides/config-toml.md#filesystem). Only the primary repo's
`.amika/config.toml` is applied — see
[multi-repo rigs](https://docs.amika.dev/guides/configuration.md#multi-repo-rigs).

### `repos`

| Type | Default | Summary |
| - | - | - |
| array of GitHub repo URLs | empty | Cloned at their default branch into `~/workspace/<repo-name>`. DB-wins-all. |

## `[agent_credentials]`

Per-agent default credential (TOML only, no database layer). See
[details](https://docs.amika.dev/guides/config-toml.md#agent_credentials).

| Field | Type | Summary |
| - | - | - |
| `type` | `"api_key"` or `"oauth"` | Credential type to use. |
| `name` | string | Name of the credential to select. |

Keys are agent kinds (`claude`, `codex`); unknown kinds are ignored.

## `[workflow]`

Hosted multi-step agent workflow. See [details](https://docs.amika.dev/guides/config-toml.md#workflow).

| Key | Type | Summary |
| - | - | - |
| `default_agent` | `"claude"` or `"codex"` | Optional default agent; defaults to Claude |
| `start` | string | Required first step name |
| `steps.<name>.prompt_file` | string | Required repo-relative prompt file |
| `steps.<name>.on_success` | string | Optional next step after success |
| `steps.<name>.on_failure` | string | Optional next step after failure |

## Related docs

* [How configuration works](https://docs.amika.dev/guides/configuration.md) — resolution precedence and application
* [config.toml reference](https://docs.amika.dev/guides/config-toml.md) — full field-by-field spec
* [Repository configuration](https://docs.amika.dev/reference/repository-configuration.md) — reference-tab overview
* [Services](https://docs.amika.dev/reference/services.md) — service runtime behavior


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