Sandbox lifecycle

A sandbox progresses through a small set of states. This guide covers each transition.

State values

State	Meaning
`initializing`	Provisioning; not yet reachable
`active`, `running`, `started`	Reachable; the SDK treats all three as “ready”
`stopped`	Paused. Can be resumed with `start`
`failed`	Provisioning or runtime failure. The wait helpers throw on this

The server may introduce new state values over time. The SDK wait helpers treat anything not in the lists above (except failed) as “still working”, so unknown values won’t break your code.

List sandboxes

amika sandbox list

const all = await amika.listSandboxes();
for (const sb of all) {
  console.log(sb.name, sb.state, sb.createdAt);
}

Stop a running sandbox

amika sandbox stop dev-box

await amika.stopSandbox("dev-box");
await amika.waitForSandboxStop("dev-box");

waitForSandboxStop polls every 3 seconds until the sandbox enters stopped. No client-side timeout — it throws if the sandbox transitions to failed.

Start a stopped sandbox

amika sandbox start dev-box

await amika.startSandbox("dev-box");
await amika.waitForSandboxStart("dev-box");

waitForSandboxStart polls every 3 seconds until the sandbox is in one of active / running / started.

Delete a sandbox

# Prompts for confirmation
amika sandbox delete dev-box

# Skip the prompt
amika sandbox delete dev-box --force

# Multiple at once
amika sandbox delete dev-box-1 dev-box-2 --force

# Also clean up volumes the sandbox owned
amika sandbox delete dev-box --force --delete-volumes

await amika.deleteSandbox("dev-box");

The CLI’s --delete-volumes / --keep-volumes flags control what happens to associated volumes; the SDK call always deletes the sandbox record and the server handles cleanup.

End-to-end example

const name = "dev-box";

// Create
await amika.createSandbox({ name, preset: "coder" });
await amika.waitForSandbox(name);

// Use it…
await amika.agentSend(name, { message: "Run the test suite" });

// Stop to pause cost
await amika.stopSandbox(name);
await amika.waitForSandboxStop(name);

// Later: resume
await amika.startSandbox(name);
await amika.waitForSandboxStart(name);

// When done
await amika.deleteSandbox(name);

Get started

Sandboxes

Agents and sessions

Code validation

Credentials

Advanced

Sandbox lifecycle

State values

List sandboxes

Stop a running sandbox

Start a stopped sandbox

Delete a sandbox

End-to-end example

Next steps

Create a sandbox

SSH and connect

Sandbox configuration reference

​State values

​List sandboxes

​Stop a running sandbox

​Start a stopped sandbox

​Delete a sandbox

​End-to-end example

​Next steps

Create a sandbox

SSH and connect

Sandbox configuration reference

State values

List sandboxes

Stop a running sandbox

Start a stopped sandbox

Delete a sandbox

End-to-end example

Next steps