> ## 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.

# Repository configuration

> Configure sandbox defaults for a repository with .amika/config.toml.

Repository configuration lets you commit sandbox settings alongside your code in `.amika/config.toml`. When a sandbox is created from a repository, Amika reads this file and applies the settings automatically — every collaborator gets the same environment without passing extra flags.

## File location

```
<repo-root>/
  .amika/
    config.toml
```

Amika looks for this file at the root of the repository whenever you use `--git` with `amika sandbox create`, or when creating a sandbox from a repository on the hosted platform.

## Configuration resolution

Repository configuration acts as a template for sandboxes. Settings can come from multiple sources, and Amika resolves them in priority order:

| Priority    | Source                      | Description                              |
| ----------- | --------------------------- | ---------------------------------------- |
| 1 (highest) | **API request / CLI flags** | Values provided at sandbox creation time |
| 2           | **Database**                | Values saved via the web UI              |
| 3           | **`.amika/config.toml`**    | Committed in the repository              |
| 4 (lowest)  | **Built-in default**        | Fallback when nothing else is configured |

The first non-empty value wins. Each configuration dimension (setup script, start script, env vars, services, sandbox settings, additional repos, and agent credential defaults) is resolved independently.

<Tip>
  When you save a setting via the web UI, it overrides the corresponding `.amika/config.toml` value for all future sandboxes. The UI shows a notice when a value originates from the TOML file.
</Tip>

## `[lifecycle]` — Setup and start scripts

Declare lifecycle scripts that run at sandbox initialization. Paths are relative to the repository root.

```toml theme={null}
[lifecycle]
setup_script = "scripts/setup.sh"
start_script = "scripts/start.sh"
```

### `setup_script`

The setup script runs once before the container command starts. It is mounted into the container at `/usr/local/etc/amikad/setup/setup.sh` and runs with the working directory set to the agent's working directory (`$AMIKA_AGENT_CWD`).

**Requirements:**

* The script must be executable (`chmod +x`).
* Exit with status code `0` on success. A non-zero exit prevents the container command from running.

**CLI override:** passing `--setup-script` to `amika sandbox create` takes priority over the TOML value.

| Flags passed                              | Source used                       |
| ----------------------------------------- | --------------------------------- |
| `--git` only                              | `.amika/config.toml` (if present) |
| `--git --setup-script ./script.sh`        | `--setup-script` flag             |
| `--setup-script ./script.sh` (no `--git`) | `--setup-script` flag             |

### `start_script`

The start script runs each time a stopped sandbox is started again — not during the initial create, where only `setup_script` runs. Use it for steps that must repeat whenever a sandbox resumes (starting a dev server, re-establishing a tunnel) rather than one-time provisioning. It is re-read on each start, so edits take effect without recreating the sandbox. It is mounted at `/usr/local/etc/amikad/setup/start.sh`.

The same requirements as `setup_script` apply: the script must be executable and exit `0`. The built-in default is a no-op (`exit 0`).

## `[env]` — Environment variables

Declare environment variables that are set inside the sandbox. Values can be plain strings or references to secrets in the Amika secrets store.

```toml theme={null}
[env]
# Plain string — set as-is
DATABASE_HOST = "localhost"
NODE_ENV = "production"

# Secret reference — resolved at sandbox creation
ANTHROPIC_API_KEY = { secret = "my-anthropic-key" }

# Service reference — resolved during sandbox initialization
API_URL = { service = "api", field = "url" }
API_HOST = { service = "api", field = "host" }
API_PORT = { service = "api", field = "port" }
```

Variable names must be `UPPER_SNAKE_CASE`.

Secrets referenced with `{ secret = "name" }` must exist in the remote secrets store before sandbox creation. Push them with `amika secret push` or through the web UI.

Service references (`{ service = "<name>", field = "url" | "host" | "port" }`) resolve to a service declared in the same file's `[services.<name>]` section. `field = "url"` gives the public URL for external access. `field = "host"` gives the hostname of that URL (no scheme, port, or path). `field = "port"` gives the host-side port (inside the sandbox) — use it when one service running in the sandbox needs to reach another over localhost.

**Merge semantics:** environment variables are merged per-key. Database entries override TOML entries with the same name, but TOML-only entries are preserved.

## `[services.<name>]` — Service definitions

Declare named services with port bindings and URL schemes. See [Services](/reference/services) for the full reference.

```toml theme={null}
[services.api]
port = 4838
url_scheme = "http"

[services.frontend]
ports = [3000, "3001/tcp"]
url_scheme = [
  { port = 3000, scheme = "https" },
]
```

**Merge semantics:** if any service definitions are saved via the web UI, those are used exclusively and TOML definitions are ignored (DB-wins-all).

## `[sandbox]` — Sandbox settings

Set default sandbox preset, size, and snapshot for the repository.

```toml theme={null}
[sandbox]
preset = "coder"             # "coder" or "coder-dind"
size = "m"                   # "xs", "m", "l", or "xl"
snapshot = "custom-snapshot" # friendly snapshot label
```

| Field      | Values                | Description                                                        |
| ---------- | --------------------- | ------------------------------------------------------------------ |
| `preset`   | `coder`, `coder-dind` | Base image preset. `coder-dind` includes Docker-in-Docker support. |
| `size`     | `xs`, `m`, `l`, `xl`  | Sandbox resource allocation.                                       |
| `snapshot` | string                | Friendly label of a snapshot captured for this repository.         |

These values are used as defaults when creating a sandbox from this repository. They can be overridden at creation time via the web UI or API.

`snapshot` takes the **friendly label** (for example `custom-snapshot`), not the org-qualified name. Amika resolves it to the full snapshot for your org at creation time, so the config stays portable across orgs. If the named snapshot is missing or no longer owned by your org, the create falls back to the preset/size path rather than failing.

You can also set repository-level preset, size, and snapshot defaults from the Edit Repository page in the web UI without committing a TOML change — those values become the "Database" layer in the resolution table above and win over any `[sandbox]` values in `.amika/config.toml`.

## `[filesystem]` — Additional repos

Clone extra repositories into the sandbox alongside the primary repo.

```toml theme={null}
[filesystem]
repos = [
  "https://github.com/gofixpoint/amika",
  "https://github.com/gofixpoint/amika-mono",
]
```

Each entry is a GitHub repository URL. Repos are cloned at their default branch into `~/workspace/<repo-name>`. The repo that the config lives in (the primary repo) is inferred automatically and does not need to be listed; if you list it, it is deduped.

Non-GitHub URLs and URLs that aren't a bare `owner/repo` (for example links to `/tree/main`) are skipped. Each additional repo is subject to the same per-user GitHub access check as the primary repo — an inaccessible repo fails the create.

**Merge semantics:** DB-wins-all. If additional repos are saved via the Edit Repository UI, that list is used exclusively and the TOML list is ignored.

<Note>
  Additional repos are cloned during the hosted-platform initialization phase. Providers without that phase (for example local Docker) clone only the primary repo and log that the extras were skipped.
</Note>

## `[agent_credentials]` — Agent credential defaults

Pin which credential each agent uses by default when creating a sandbox from this repository.

```toml theme={null}
[agent_credentials]
claude = { type = "api_key" }
codex = { type = "oauth", name = "work-codex" }
```

Each key is an agent kind (`claude` or `codex`). The value is a table with optional `type` (`api_key` or `oauth`) and `name` (the credential's name). Entries for unknown agent kinds are ignored, so a repo can declare a default for an agent the server doesn't support yet. This dimension lives only in TOML — there is no database layer.

## Branch selection

When `--branch` is specified on `amika sandbox create`, the `.amika/config.toml` file is read from that branch rather than the repository's default branch. This allows different branches to carry different sandbox configurations.

```bash theme={null}
amika sandbox create --git --branch feature/new-api
```

## Example

Given this repository layout:

```
my-project/
  .amika/
    config.toml
    setup.sh
  src/
    ...
```

With this `config.toml`:

```toml theme={null}
[lifecycle]
setup_script = ".amika/setup.sh"

[env]
NODE_ENV = "development"
API_KEY = { secret = "my-api-key" }

[services.web]
port = 3000
url_scheme = "http"

[sandbox]
preset = "coder"
size = "m"
```

Running `amika sandbox create --git` from anywhere inside `my-project` will:

1. Clone the repository into the sandbox.
2. Mount `.amika/setup.sh` as the setup script.
3. Set `NODE_ENV=development` and resolve `API_KEY` from the secrets store.
4. Publish port 3000 with an HTTP URL.
5. Use the `coder` preset with medium resource allocation.

## Related docs

* [Sandbox configuration](/reference/sandbox-configuration) — CLI flags, credential mounting, reserved ports
* [Services](/reference/services) — full `[services.<name>]` reference
* [config.toml reference](/reference/config-toml) — exhaustive field reference