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: 
[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 script that runs before the container command
  • [env] — environment variables and secret references
  • [services.<name>] — named services with port bindings and URL schemes
  • [sandbox] — default sandbox preset and size

​
[lifecycle]

Controls sandbox initialization.

​
setup_script

TypeString (file path)
RequiredNo
DefaultBuilt-in no-op script (exit 0)
Path to an executable script that is mounted into the container at /usr/local/etc/amikad/setup/setup.sh and run before the container command starts. Relative paths are resolved from the repository root (the directory containing .git). Absolute paths are used as-is. 
[lifecycle]
setup_script = "scripts/setup.sh"
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.

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

[env]
DATABASE_HOST = "localhost"
NODE_ENV = "production"
PORT = "3000"
The value is set as-is in the sandbox 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 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.

​
Validation rules

RuleDetail
Name formatMust match ^[A-Z_][A-Z0-9_]*$ (UPPER_SNAKE_CASE)
Value typeString or { secret = "..." } table
Secret nameMust be a non-empty string
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

FieldTypeRequiredDescription
portinteger or "port/protocol" stringNoSingle port declaration
portsarray of integer or "port/protocol" stringNoMultiple port declarations
url_schemestring or array of { port, scheme } tablesNoURL 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

RuleDetail
Port range1–65535
Reserved rangePorts 60899–60999 are reserved for Amika internal services and are rejected
Protocoltcp or udp
Mutual exclusivityCannot specify both port and ports on the same service
UniquenessNo duplicate (port, protocol) pair across all services in the file
url_scheme portsMust reference a port declared in the same service
url_scheme uniquenessNo duplicate port entries within url_scheme
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: 
[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 sandbox settings for the repository.

​
preset

TypeString
RequiredNo
Default"coder"
Values"coder", "coder-dind"
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

TypeString
RequiredNo
Default"m"
Values"xs", "m"
The resource allocation size for sandboxes created from this repository. 
[sandbox]
preset = "coder-dind"
size = "m"

​
Merge semantics

Preset and size are resolved independently. Database values (saved via the web UI) override TOML values.

​
Full example

[lifecycle]
setup_script = ".amika/setup.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"