Sandbox configuration

Sandbox configuration controls the runtime environment of individual sandboxes. Many settings can be defined in a repository configuration and applied automatically, but you can also override or extend them with CLI flags and platform settings.

Setup scripts

Use --setup-script to mount a script at /usr/local/etc/amikad/setup/setup.sh. Amika runs this script before the container command starts.

amika sandbox create --name dev-box --setup-script ./install-deps.sh

Script requirements

Make the script executable with chmod +x.
Setup scripts run with the working directory set to the agent’s working directory ($AMIKA_AGENT_CWD).
Exit with status code 0 on success.
Keep setup deterministic so sandbox startup stays predictable.

#!/bin/bash
set -e

apt-get update
apt-get install -y ripgrep
pip install numpy

How it works

Preset images include a no-op /usr/local/etc/amikad/setup/setup.sh and an entrypoint that runs it before CMD. When you pass --setup-script, your file is mounted over the no-op script.

If the setup script exits non-zero, the container command does not run.

You can also define setup scripts in .amika/config.toml so they apply automatically when creating sandboxes from a repository. The --setup-script flag always takes priority.

Git repository cloning

--git clones a git repository into the sandbox at /home/amika/workspace/<repo-name>.

# Clone the current repo (clean clone)
amika sandbox create --git

# Include untracked/uncommitted files
amika sandbox create --git --no-clean

# Clone the repo containing a specific path
amika sandbox create --git ./src

# Clone a specific branch
amika sandbox create --git --branch feature/new-api

When --git is used, Amika also looks for a .amika/config.toml file at the root of the repository and applies it automatically.

The volume name is derived from the sandbox name and repo name, e.g. amika-git-teal-tokyo-Hello-World-<timestamp>.
Deleting the sandbox does not automatically delete the git volume; use amika volume delete when you no longer need it.

Overriding repository configuration

When a sandbox is created from a repository, settings from .amika/config.toml are applied as defaults. You can override any of these at creation time:

# Override the setup script
amika sandbox create --git --setup-script ./my-other-script.sh

# Override the preset
amika sandbox create --git --preset coder-dind

# Add extra port bindings beyond what's in config.toml
amika sandbox create --git --port 5432:5432

On the hosted platform, settings saved via the web UI take priority over .amika/config.toml values. See configuration resolution for the full precedence order.

Agent credential auto-mounting

Amika auto-discovers credential files on your host and mounts them into the sandbox. This gives agents access to credentials without modifying host files.

Supported files

Claude Code

~/.claude.json.api
~/.claude.json
~/.claude/.credentials.json
~/.claude-oauth-credentials.json

Codex

~/.codex/auth.json

OpenCode

~/.local/share/opencode/auth.json
~/.local/state/opencode/model.json

Only files that exist on your host are mounted. Inside containers, these files appear under /home/amika/ with matching relative paths.

Sandbox lifecycle

Hosted sandboxes have two idle-timeout knobs that control when they stop and when they’re deleted:

Setting	Default	Range	Behavior
Auto-stop interval	30 minutes	0–10080 (7 days)	Time of idleness before the sandbox is stopped. `0` disables auto-stop.
Auto-delete interval	Keep on stop	0–10080 (7 days)	Time after stopping before the sandbox is deleted. The default keeps stopped sandboxes indefinitely.

Both intervals are expressed in minutes and apply to the hosted platform (remote sandboxes). Stopped sandboxes can be resumed with amika sandbox start <name>.

Auto-stop and auto-delete intervals are currently settable only when creating a sandbox through the web UI or by passing auto_stop_interval / auto_delete_interval to POST /api/sandboxes. There’s no CLI flag and no .amika/config.toml field for these yet.

Reserved ports

Amika reserves container ports 60899–60999 (101 ports) for internal services that run inside sandboxes. User workloads and setup scripts should avoid binding to ports in this range.

Port	Service	Status
60999	amikad daemon	Reserved
60998	OpenCode web UI	Active
60899–60997	(unassigned, reserved for use)	Reserved

The OpenCode web server starts automatically on port 60998 when OpenCode is installed in the container and AMIKA_OPENCODE_WEB is not set to 0. The port number is written to /run/amikad/opencode-web.port at startup.

Repository configuration — .amika/config.toml and per-repo settings
Services — named service definitions with port mappings
Presets — preset images and container layout

CLI and platform

Repository configuration

HTTP API

Sandbox configuration

Setup scripts

Script requirements

How it works

Git repository cloning

Overriding repository configuration

Agent credential auto-mounting

Supported files

Sandbox lifecycle

Reserved ports

​Setup scripts

​Script requirements

​How it works

​Git repository cloning

​Overriding repository configuration

​Agent credential auto-mounting

​Supported files

​Sandbox lifecycle

​Reserved ports

​Related docs

Setup scripts

Script requirements

How it works

Git repository cloning

Overriding repository configuration

Agent credential auto-mounting

Supported files

Sandbox lifecycle

Reserved ports

Related docs