Repository configuration

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.

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.

`[lifecycle]` — Setup and start scripts

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

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

[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 for the full reference.

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

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

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

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.

`[agent_credentials]` — Agent credential defaults

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

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

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:

[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:

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

Sandbox configuration — CLI flags, credential mounting, reserved ports
Services — full [services.<name>] reference
config.toml reference — exhaustive field reference

CLI and platform