Skip to main content
A sandbox 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 sandbox 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 sandbox: where it can come from, how Amika resolves conflicts, and how it behaves for multi-repo and repo-less sandboxes. For the full field-by-field spec, see config.toml reference.

​
What a repo config controls

.amika/config.toml is a template for the sandboxes created from a repository. Each section maps to one dimension of the sandbox:
  • [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.
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 sandbox 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 sandbox at once. A value saved through the web UI becomes the “Database” layer and overrides the corresponding .amika/config.toml value for all future sandboxes; 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 sandbox preset is a good example — you can declare it once in the repo, override it per sandbox 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 sandbox created from the repo.

​
Multi-repo sandboxes

A sandbox 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 sandbox 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 sandbox needs in the primary repo’s config.

​
Repo-less sandboxes

A repository is optional. A sandbox 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 sandbox for how the CLI picks (or skips) a repo.