> ## 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 sandbox
defaults for that repository. This page is a compact lookup of every key.

<Info>
  For concepts, examples, validation rules, and merge semantics, see the full
  guides:
  [How configuration works](/guides/configuration) (precedence, multi-repo,
  repo-less) and the
  [config.toml reference](/guides/config-toml) (field-by-field spec).
</Info>

<Note>
  The open-source `amika` CLI parses only `[lifecycle].setup_script` and
  `[services.<name>]`. The remaining sections are applied by the hosted platform.
  The singular `[service.<name>]` is accepted as an alias for `[services.<name>]`.
</Note>

## `[lifecycle]`

Setup and start scripts. See [details](/guides/config-toml#lifecycle).

| Key            | Type          | Default | Summary                                                                                     |
| -------------- | ------------- | ------- | ------------------------------------------------------------------------------------------- |
| `setup_script` | string (path) | no-op   | Executable run once before the container command starts. Overridable with `--setup-script`. |
| `start_script` | string (path) | no-op   | Executable run each time a stopped sandbox is restarted (hosted only).                      |

## `[env]`

Environment variables set inside the sandbox. See
[details](/guides/config-toml#env) and
[env vars vs. secrets](/guides/env-vars-and-secrets).

| 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](/guides/config-toml#services)
and [Services](/reference/services).

| 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 sandbox settings. See [details](/guides/config-toml#sandbox).

| Key        | Type   | Default   | Values                                                |
| ---------- | ------ | --------- | ----------------------------------------------------- |
| `preset`   | string | `"coder"` | `"coder"`, `"coder-dind"`                             |
| `size`     | string | `"m"`     | `"xs"`, `"m"`, `"l"`, `"xl"`                          |
| `snapshot` | string | none      | Friendly snapshot label (not the org-qualified name). |

## `[filesystem]`

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

### `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](/guides/config-toml#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.

## Related docs

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