Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.amika.dev/llms.txt

Use this file to discover all available pages before exploring further.

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:
SettingDefaultRangeBehavior
Auto-stop interval30 minutes0–10080 (7 days)Time of idleness before the sandbox is stopped. 0 disables auto-stop.
Auto-delete intervalKeep on stop0–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.
PortServiceStatus
60999amikad daemonReserved
60998OpenCode web UIActive
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.