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.

This page is the reference-tab summary. For the full concept guide — including multi-repo and repo-less sandboxes — see How configuration works. For the field-by-field spec, see the config.toml reference.

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.

Prefer .amika/config.toml as your source of truth: it is versioned with your code, reviewable in pull requests, and easy for coding agents to edit. When you save a setting via the web UI it becomes the Database layer and overrides the corresponding TOML value for all future sandboxes; the UI shows a notice when a value originates from the TOML file.

Sections at a glance

.amika/config.toml has these tables. Each links to its full spec.

Table	Purpose
`[lifecycle]`	Setup and start scripts
`[env]`	Environment variables and secret references
`[services.<name>]`	Named services with port bindings and URL schemes
`[sandbox]`	Default preset, size, and boot snapshot
`[filesystem]`	Additional repos to clone
`[agent_credentials]`	Per-agent credential defaults

`[lifecycle]` — Setup and start scripts

Lifecycle scripts run at sandbox initialization. Paths are relative to the repository root.

[lifecycle]
setup_script = "scripts/setup.sh"
start_script = "scripts/start.sh"

setup_script runs once before the container command starts, mounted at /usr/local/etc/amikad/setup/setup.sh, with the working directory set to $AMIKA_AGENT_CWD. It must be executable and exit 0. Passing --setup-script to amika sandbox create takes priority.
start_script runs each time a stopped sandbox is started again — not on the initial create. It is re-read on each start. Use it for steps that must repeat on resume (starting a dev server, re-opening a tunnel).

Flags passed	Setup 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

See the [lifecycle] spec for full details.

`[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, cloned at its default branch into ~/workspace/<repo-name>. The primary repo is inferred automatically and need not be listed.

Only the primary repo’s .amika/config.toml is applied. A .amika/config.toml in an additional repo is ignored. See multi-repo sandboxes.

See the [filesystem] spec for validation and merge semantics.

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.

How configuration works — concept guide: precedence, multi-repo, repo-less
config.toml reference — full field-by-field spec
Sandbox configuration — CLI flags, credential mounting, reserved ports
Services — full [services.<name>] reference

CLI and platform