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
--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
.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
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.
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 |
AMIKA_OPENCODE_WEB is not set to 0. The port number is written to /run/amikad/opencode-web.port at startup.
