Prerequisites
- An Amika account and an API token. The CLI uses
amika auth login; the SDK expects you to source a token viaaccessTokenortokenSource. - (For the
--gitflow) Git installed and a repo to mount. - For the SDK:
npm install @amika/sdk.
Step 1 — Create the sandbox
The simplest sandbox uses thecoder preset (Ubuntu 24.04 with Node, Python,
and the Claude Code / Codex / OpenCode CLIs pre-installed).
--git (CLI) or repoUrl (SDK). The
CLI’s --git accepts a local path or a git URL; the SDK accepts a URL.
How the CLI picks a repo
- Run
amika sandbox createfrom inside a git repo and that repo is used automatically — no flag needed. - Outside a repo (or to target a different one), pass
--git <path-or-URL>. The value accepts a local path or a git URL (HTTPS or SSH). - Pass
--no-gitto skip auto-detection and create a repo-less sandbox — a sandbox with no repository mounted. This is useful for scratch environments or when you clone repos yourself after connecting.
A repo-less sandbox still boots a full environment; it just starts without a
checked-out repository. Configuration for multi-repo and repo-less sandboxes is
covered in the Repository configuration
guide.
Step 2 — Wait until it’s ready
A new sandbox starts in stateinitializing and transitions to active /
running / started once it’s reachable.
waitForSandbox throws an AmikaError if the sandbox reaches the failed
state. New state values can appear over time — the wait helper treats
active, running, and started as ready and anything else (except
failed) as still working.