Skip to main content
The .amika/config.toml file lives at the root of a Git repository and declares sandbox defaults for that repository. When a sandbox is created from the repo, Amika reads this file and applies the settings automatically. For an overview of how repository configuration works and how it interacts with other configuration sources, see Repository configuration.

Quick start

A minimal config that sets up a Node project with a secret and a web server:

Sections

The open-source amika CLI parses only [lifecycle].setup_script and [services.<name>]. The remaining sections are applied by the hosted platform when a sandbox is created from a repository.

[lifecycle]

Controls sandbox initialization. Both keys are optional; a repository can define only setup, only start, or both.

setup_script

Path to an executable script that is mounted into the container at /usr/local/etc/amikad/setup/setup.sh and run once before the container command starts. Relative paths are resolved from the repository root (the directory containing .git). Absolute paths are used as-is. Requirements:
  • Must be executable (chmod +x).
  • Must exit with status code 0 on success. A non-zero exit prevents the container command from running.
  • Runs with the working directory set to $AMIKA_AGENT_CWD.
CLI override: --setup-script on amika sandbox create takes priority over this value.

start_script

Path to an executable script mounted at /usr/local/etc/amikad/setup/start.sh. Unlike setup_script, it does not run on the initial create — it runs each time a stopped sandbox is started again. It is re-read on each start, so edits take effect without recreating the sandbox. Use it for steps that must repeat whenever a sandbox resumes — starting a long-running dev server, re-opening a tunnel — rather than one-time provisioning, which belongs in setup_script. Relative paths resolve from the repository root. The same executability and exit-code requirements as setup_script apply. This key is applied by the hosted platform. The open-source CLI does not run a start script.

[env]

Declares environment variables that are set inside the sandbox. Each key is a variable name and each value is either a plain string or a secret reference.

Plain string

The value is set as-is in the sandbox environment.

Secret reference

The secret field references a secret by name in the Amika secrets store. The secret is resolved at sandbox creation time and its value is injected as the environment variable. Secrets must be pushed before sandbox creation via amika secret push or the web UI.

Service reference

The service field references a service declared in the same file’s [services.<name>] section. The field selects which attribute to inject:
  • "url" — the public URL of the service (e.g. https://<sandbox>.preview.amika.dev). Requires the service to have a url_scheme.
  • "host" — the hostname of that public URL (e.g. <sandbox>.preview.amika.dev), with no scheme, port, or path. Like "url", requires the service to have a url_scheme.
  • "port" — the host-side port (inside the sandbox) the service is exposed on.
Service references are resolved during sandbox initialization and written to the sandbox environment. They’re useful when one service needs to reach another by URL.

Validation rules

If validation fails, the [env] section is skipped and a warning is logged. Other sections are still applied.

Merge semantics

Environment variables are merged per-key across sources. Database entries (saved via the web UI) override TOML entries with the same name, but TOML-only entries are preserved.

[services.<name>]

Declares named services with port bindings and optional URL schemes. Each [services.<name>] section defines one service. See Services for usage examples and runtime behavior.

Fields

port and ports are mutually exclusive. A service may omit both to act as a metadata-only entry with no port bindings.

Port format

Each port value is either:
  • Integer — interpreted as containerPort/tcp (TCP is the default protocol).
  • String "containerPort/protocol" — sets the protocol explicitly.

url_scheme

Controls URL generation for service ports. Allowed values: "http", "https". Single-port services accept a string or a single-element array:
Multi-port services must use the array form. Only listed ports get URLs:

Validation rules

If validation fails, service definitions are skipped and a warning is logged. Other sections (e.g. [lifecycle], [env]) are still applied.

Merge semantics

Service definitions use DB-wins-all semantics: if any service definitions are saved via the web UI, those are used exclusively and TOML definitions are ignored.

Examples

Simple web server:
API with multiple ports:
Metadata-only service (no ports):

[sandbox]

Sets default sandbox settings for the repository.

preset

The base image preset for sandboxes created from this repository.
  • coder — Ubuntu 24.04 with Git, Node.js, Python, and agent CLIs (Claude Code, Codex, OpenCode).
  • coder-dind — Same as coder with Docker-in-Docker support.
See Presets for full details on what each preset includes.

size

The resource allocation size for sandboxes created from this repository.

snapshot

The friendly label of a snapshot captured for this repository (for example custom-snapshot), not the org-qualified Daytona name. Amika maps the label to the full snapshot for your org at creation time, keeping the config portable across orgs.
When a sandbox is created, the snapshot layer order is: an explicit snapshot in the API request, then this repository default, then a repository custom image, then the preset/size default. If the named snapshot is missing or no longer owned by your org, Amika logs a warning and falls through to the preset/size path rather than failing the create.

Merge semantics

Preset, size, and snapshot are resolved independently. Database values (saved via the web UI) override TOML values. There is no built-in repository default for any of the three — when none is configured, the Create Sandbox dialog applies its own UI defaults.

[filesystem]

Declares extra repositories to clone into the sandbox alongside the primary repo.

repos

Each repo is cloned at its default branch into ~/workspace/<repo-name>. The primary repo (the one this config lives in) is inferred automatically and need not be listed; if listed, it is deduped.

Validation and resolution

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]

Pins which credential each agent uses by default for sandboxes created from this repository. This dimension lives only in TOML — there is no database layer.
Each key is an agent kind. Each value is an inline table:

Full example