Repository configuration

Repository configuration lets you commit rig settings alongside your code in .amika/config.toml. When a rig 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 rigs — 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 selected by amika rig create, whether the CLI detects the repository from the current directory or you pass --git <path-or-URL>.

Configuration resolution

Repository configuration acts as a template for rigs. 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 rig 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, rig settings, additional repos, agent credential defaults, and workflows) 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 rigs; 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
`[workflow]`	Multi-step agent workflow

`[lifecycle]` — Setup and start scripts

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

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

setup_script runs once during initial creation with the working directory set to $AMIKA_AGENT_CWD. The hosted platform reads the file’s contents, so its executable bit in Git is not required. A nonzero exit marks setup as failed, but the rig remains accessible. Passing --setup-script to amika rig create takes priority.
start_script runs each time a stopped rig 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
Auto-detected repository	`.amika/config.toml` (if present)
`--setup-script ./script.sh`	`--setup-script` flag
`--no-setup`	Built-in no-op script

See the [lifecycle] spec for full details.

`[filesystem]` — Additional repos

Clone extra repositories into the rig 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 rigs.

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

Branch selection

When --branch is specified on amika rig 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 rig configurations.

amika rig create --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 rig create from anywhere inside my-project will:

Clone the repository into the rig.
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
Rig configuration — CLI flags, credential mounting, reserved ports
Services — full [services.<name>] reference

CLI and platform