Skip to main content
Use sandbox configuration to prepare agent environments before work starts.

​
Setup scripts

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

​
Example

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

# materialize
amika materialize --setup-script ./install-deps.sh --cmd "echo done" --destdir /tmp/out

​
Script requirements

  • Make the script executable with chmod +x.
  • 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 /opt/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.

​
Agent credential auto-mounting

Amika auto-discovers credential files on your host and mounts them as rwcopy. This gives agents access to credentials inside the sandbox 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.