config.toml reference

This is the full field-by-field guide to .amika/config.toml, the file that declares rig defaults for a repository. For how these settings reach a rig — resolution precedence, multi-repo, and repo-less behavior — read How configuration works first. The file lives at the root of a Git repository:

<repo-root>/
  .amika/
    config.toml

Quick start

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

[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"

Sections

[lifecycle] — setup and start scripts
[env] — environment variables and secret references
[services.<name>] — named services with port bindings and URL schemes
[sandbox] — default rig preset, size, and snapshot
[filesystem] — additional repos to clone alongside the primary repo
[agent_credentials] — per-agent credential defaults

`[lifecycle]`

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

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

`setup_script`


Type	String (file path)
Required	No
Default	Built-in no-op script (`exit 0`)

Path to a repository script whose contents Amika installs as the setup hook. It runs once during initial rig creation. Use a path relative to the repository root. Requirements:

Include a shebang and exit with status code 0 on success.
The executable bit in Git is not required for hosted rigs.
A nonzero exit records a setup failure, but the hosted rig remains accessible.
The script runs with the working directory set to $AMIKA_AGENT_CWD.

CLI override: --setup-script on amika rig create takes priority over this value.

`start_script`


Type	String (file path)
Required	No
Default	Built-in no-op script (`exit 0`)

Path to a repository script that Amika installs as the start hook. Unlike setup_script, it does not run on the initial create. It runs each time a stopped rig is started again. It is re-read on each start, so edits take effect without recreating the rig. Use it for steps that must repeat whenever a rig resumes, such as starting a long-running dev server or re-opening a tunnel. Put one-time provisioning in setup_script. Relative paths resolve from the repository root. The same exit-code behavior as setup_script applies. This key is applied by the hosted platform. The open-source Go config parser does not support a start script.

`[env]`

Declares environment variables that are set inside the rig. Each key is a variable name and each value is either a plain string or a reference table. See Environment variables vs. secrets for how to choose between a plain value and a secret reference.

Plain string

[env]
DATABASE_HOST = "localhost"
NODE_ENV = "production"
PORT = "3000"

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

Secret reference

[env]
ANTHROPIC_API_KEY = { secret = "my-anthropic-key" }
AWS_SECRET_KEY = { secret = "My AWS Secret" }

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

Service reference

[env]
WEB_URL = { service = "web", field = "url" }
WEB_HOST = { service = "web", field = "host" }
WEB_PORT = { service = "web", field = "port" }

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://<rig>.preview.amika.dev). Requires the service to have a url_scheme.
"host" — the hostname of that public URL (e.g. <rig>.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 rig) the service is exposed on.

Service references are resolved during rig initialization and written to the rig environment. They’re useful when one service needs to reach another by URL.

Validation rules

Rule	Detail
Name format	Must match `^[A-Z_][A-Z0-9_]*$` (UPPER_SNAKE_CASE)
Value type	String, `{ secret = "..." }` table, or `{ service = "...", field = "..." }` table
Secret name	Must be a non-empty string
Service name	Must match a service declared in `[services.<name>]`
Service field	Must be `"url"`, `"host"`, or `"port"`

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.

The singular [service.<name>] is accepted as an alias for [services.<name>]. Use one form or the other consistently within a file.

Fields

Field	Type	Required	Description
`port`	integer or `"port/protocol"` string	No	Single port declaration
`ports`	array of integer or `"port/protocol"` string	No	Multiple port declarations
`url_scheme`	string or array of `{ port, scheme }` tables	No	URL generation scheme

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.

# These are equivalent
port = 4838
port = "4838/tcp"

`url_scheme`

Controls URL generation for service ports. Allowed values: "http", "https". Single-port services accept a string or a single-element array:

[services.api]
port = 4838
url_scheme = "http"

Multi-port services must use the array form. Only listed ports get URLs:

[services.web]
ports = [4211, "9872/tcp", "4982/udp"]
url_scheme = [
  { port = 4211, scheme = "http" },
  { port = 9872, scheme = "https" },
]
# 4982/udp gets no URL

Validation rules

Rule	Detail
Port range	1–65535
Reserved range	Ports 60899–60999 are reserved for Amika internal services and are rejected
Protocol	`tcp` or `udp`
Mutual exclusivity	Cannot specify both `port` and `ports` on the same service
Uniqueness	No duplicate `(port, protocol)` pair across all services in the file
url_scheme ports	Must reference a port declared in the same service
url_scheme uniqueness	No duplicate port entries within `url_scheme`

If a service definition fails validation, rig creation fails with a 400 invalid_repo_config error whose message names the problem. Fix .amika/config.toml and create the rig again.

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:

[services.web]
port = 3000
url_scheme = "http"

API with multiple ports:

[services.api]
ports = [8000, "8001/udp"]
url_scheme = [
  { port = 8000, scheme = "http" },
]

Metadata-only service (no ports):

[services.worker]
# No port or ports — acts as a named reference only

`[sandbox]`

Sets default rig settings for the repository.

`preset`


Type	String
Required	No
Default	`"coder"`
Values	`"coder"`, `"coder-plus-docker"`

The base image preset for rigs created from this repository.

coder: Ubuntu 24.04 with Git, Node.js, Python, and the Claude Code, Codex, OpenCode, and Pi agent CLIs.
coder-plus-docker: Same as coder, with Docker support inside the rig.

See Presets for full details on what each preset includes.

`size`


Type	String
Required	No
Default	The provider’s `m` tier: `a0.m`, or `a1.medium` on E2B
Values	A versioned size offered by the provider, or a friendly alias

The resource allocation size for rigs created from this repository. Each provider serves one size generation. E2B serves a1, and the other hosted providers serve a0:

Generation	Sizes
`a0`	`a0.xs`, `a0.m`, `a0.l`, `a0.xl`
`a1`	`a1.tiny`, `a1.small`, `a1.medium`, `a1.large`, `a1.xlarge`

The friendly aliases are xs (or extra-small), m (or medium), l (or large), and xl (or extra-large). Aliases and sizes are case-insensitive.

[sandbox]
preset = "coder-plus-docker"
size = "m"

Friendly aliases normalize to the legacy a0 generation, so they are not portable across providers. For example, l resolves to a0.l, which E2B does not offer. Use a1.large for a large E2B rig. The API accepts versioned sizes when the selected provider offers them. The coder-plus-docker preset does not support the xs tier. Amika ignores a size value it doesn’t recognize, and falls back to the default. An unrecognized preset makes it ignore the whole [sandbox] table, including size and snapshot.

`snapshot`


Type	String
Required	No
Default	None

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.

[sandbox]
snapshot = "custom-snapshot"

When a rig 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. When neither sets a value, the platform defaults apply: the coder preset, the provider’s m size (a0.m, or a1.medium on E2B), and no snapshot.

`[filesystem]`

Declares extra repositories to clone into the rig alongside the primary repo. See Multi-repo rigs for the key rule: only the primary repo’s .amika/config.toml is applied.

`repos`


Type	Array of strings (GitHub repo URLs)
Required	No
Default	Empty (only the primary repo is cloned)

[filesystem]
repos = [
  "https://github.com/gofixpoint/amika",
  "https://github.com/gofixpoint/amika-mono",
]

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

Rule	Detail
URL form	Must be a GitHub `owner/repo` URL. Non-GitHub URLs and page URLs (`/tree/main`, query strings) are dropped.
Name collisions	Two repos with the same basename would share `~/workspace/<name>`; the first seen wins and the rest are dropped.
Access	Each repo passes the same per-user GitHub access check as the primary. An inaccessible repo fails the create with `github_repo_not_accessible`.

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 rigs created from this repository. This dimension lives only in TOML — there is no database layer.

[agent_credentials]
claude = { type = "api_key" }
codex = { type = "oauth", name = "work-codex" }

Each key is an agent kind. Each value is an inline table:

Field	Type	Required	Description
`type`	`"api_key"` or `"oauth"`	No	The credential type to use.
`name`	string	No	The name of the credential to select.

Rule	Detail
Agent kinds	`claude`, `codex`. Entries for unknown kinds are ignored, so a repo may declare a default for an agent the server doesn’t support yet.
Non-empty entry	An entry must set `type`, `name`, or both. Entries with neither are dropped.
Unknown fields	An entry with keys other than `type` and `name` is ignored.

See Inject credentials for how these defaults interact with per-rig credential selection.

Full example

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

[env]
NODE_ENV = "development"
DATABASE_URL = "postgresql://localhost:5432/mydb"
ANTHROPIC_API_KEY = { secret = "my-anthropic-key" }
AWS_ACCESS_KEY_ID = { secret = "aws-access-key" }

[services.web]
port = 3000
url_scheme = "https"

[services.api]
port = 8080
url_scheme = "http"

[services.db]
port = 5432

[services.worker]
ports = [9000, "9001/udp"]
url_scheme = [
  { port = 9000, scheme = "http" },
]

[sandbox]
preset = "coder"
size = "m"
snapshot = "custom-snapshot"

[filesystem]
repos = [
  "https://github.com/gofixpoint/amika",
]

[agent_credentials]
claude = { type = "api_key" }

How configuration works — resolution precedence, multi-repo, repo-less
config.toml key lookup — every key at a glance
Environment variables vs. secrets — choosing plain values vs. secrets
Services — service runtime behavior, port resolution, and listing

Get started

Rigs (machines)

Agents and sessions

Configuration

Connecting to rigs

Guides for agents

Advanced

config.toml reference

Quick start

Sections

`[lifecycle]`

`setup_script`

`start_script`

`[env]`

Plain string

Secret reference

Service reference

Validation rules

Merge semantics

`[services.<name>]`

Fields

Port format

`url_scheme`

Validation rules

Merge semantics

Examples

`[sandbox]`

`preset`

`size`

`snapshot`

Merge semantics

`[filesystem]`

`repos`

Validation and resolution

`[agent_credentials]`

Full example

​Quick start

​Sections

​[lifecycle]

​setup_script

​start_script

​[env]

​Plain string

​Secret reference

​Service reference

​Validation rules

​Merge semantics

​[services.<name>]

​Fields

​Port format

​url_scheme

​Validation rules

​Merge semantics

​Examples

​[sandbox]

​preset

​size

​snapshot

​Merge semantics

​[filesystem]

​repos

​Validation and resolution

​[agent_credentials]

​Full example

​Related docs

Quick start

Sections

`[lifecycle]`

`setup_script`

`start_script`

`[env]`

Plain string

Secret reference

Service reference

Validation rules

Merge semantics

`[services.<name>]`

Fields

Port format

`url_scheme`

Validation rules

Merge semantics

Examples

`[sandbox]`

`preset`

`size`

`snapshot`

Merge semantics

`[filesystem]`

`repos`

Validation and resolution

`[agent_credentials]`

Full example

Related docs