Skip to main content
A rig needs to know what image to boot, what to install, what services to expose, and which secrets to inject. Amika reads that from repository configuration — a .amika/config.toml file committed at the root of your repo. When a rig is created from the repo, Amika reads the file and applies the settings automatically, so every collaborator gets the same environment without passing extra flags.
This guide explains how configuration reaches a rig: where it can come from, how Amika resolves conflicts, and how it behaves for multi-repo and repo-less rigs. For the full field-by-field spec, see config.toml reference.

​
What a repo config controls

.amika/config.toml is a template for the rigs created from a repository. Each section maps to one dimension of the rig:
  • [lifecycle] — setup and start scripts that provision the environment.
  • [env] — environment variables and secret references.
  • [services.<name>] — named services with port bindings and public URLs.
  • [sandbox] — the default preset, size, and boot snapshot.
  • [filesystem] — additional repos to clone alongside the primary one.
  • [agent_credentials] — which stored credential each agent uses by default.
  • [workflow]: a hosted multi-step agent workflow.
Because the file lives in the repo, it is versioned with your code and easy for a coding agent to read and edit. That makes it the recommended place to declare rig settings.

​
How configuration is applied

The same setting can be declared in more than one place. Amika resolves each setting independently, taking the first non-empty value in this order: Resolution is per-dimension: a preset from a CLI flag, env vars from the TOML, and a size from a UI setting can all apply to the same rig at once. A value saved through the web UI becomes the “Database” layer and overrides the corresponding .amika/config.toml value for all future rigs; the UI shows a notice when a value originates from the TOML file.
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 — unlike UI or per-request settings, which live outside the repo. Reserve CLI flags and the UI for one-off overrides.

​
Setting a value across surfaces

Setting the rig preset is a good example — you can declare it once in the repo, override it per rig from the CLI, or set a repository default in the UI. All three feed the resolution table above.
Commit the default with your code. It applies to every rig created from the repo.

​
Multi-repo rigs

A rig can clone more than one repository. List the extra repos under [filesystem].repos in the primary repo’s config. Each is cloned into ~/workspace/<repo-name> alongside the primary.
Only the primary repo’s .amika/config.toml is applied. The primary repo is the one the rig is created from — the repo that carries the [filesystem] list. Any .amika/config.toml in an additional repo is ignored: its [env], [services], [lifecycle], and other sections have no effect. Declare everything the rig needs in the primary repo’s config.

​
Repo-less rigs

A repository is optional. A rig can boot with no repo — and therefore no .amika/config.toml. This is useful for scratch environments, or when you clone repos yourself after connecting. With no config file, every setting falls through to the API request / CLI flags layer or the built-in default. Pass the preset, size, env vars, and credentials you need at create time.
See Create a rig for how the CLI picks (or skips) a repo.