Rig lifecycle

A rig 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
`stopped`	Paused. Can be resumed with `start`
`failed`	Provisioning or runtime failure. `rig.wait()` throws on this

The server may introduce new state values over time. The SDK’s rig.wait() checks the rig’s lifecycle status and its setup status, and only treats failed as a failure, so unknown values won’t break your code.

List rigs

amika rig list

const rigs = await client.rigs.list();
for (const rig of rigs) {
  console.log(rig.name, rig.status, rig.createdAt);
}

curl https://app.amika.dev/api/v0beta1/rigs \
  -H "Authorization: Bearer $AMIKA_API_KEY"

Stop a running rig

amika rig stop dev-box

const rig = client.rigs.handle("dev-box");
await rig.stop();
await rig.wait({ status: "stopped" });

curl -X POST https://app.amika.dev/api/v0beta1/rigs/dev-box/stop \
  -H "Authorization: Bearer $AMIKA_API_KEY"

wait({ status: "stopped" }) polls every 3 seconds until the rig is stopped (or suspended), for up to 15 minutes. It throws an AmikaWaitError if the rig fails or the deadline passes.

Start a stopped rig

amika rig start dev-box

const rig = client.rigs.handle("dev-box");
await rig.start();
await rig.wait();

curl -X POST https://app.amika.dev/api/v0beta1/rigs/dev-box/start \
  -H "Authorization: Bearer $AMIKA_API_KEY"

wait() polls every 3 seconds until the rig is running and its setup succeeded, for up to 15 minutes. Over HTTP, start and stop return 202 with {"ok": true} and finish in the background. Poll GET /api/v0beta1/rigs/{id} until status and setup_status reach the values you need. Every rig path takes the rig’s ID or its name. See the HTTP API overview.

Delete a rig

# Prompts for confirmation
amika rig delete dev-box

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

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

await client.rigs.handle("dev-box").delete();

curl -X DELETE https://app.amika.dev/api/v0beta1/rigs/dev-box \
  -H "Authorization: Bearer $AMIKA_API_KEY"

End-to-end example

// Create
const rig = await client.rigs.create({ name: "dev-box", preset: "coder" });
await rig.wait();

// Use it…
await rig.send({ message: "Run the test suite" });

// Stop to pause cost
await rig.stop();
await rig.wait({ status: "stopped" });

// Later: resume
await rig.start();
await rig.wait();

// When done
await rig.delete();

Get started

Rigs (machines)

Agents and sessions

Configuration

Connecting to rigs

Guides for agents

Advanced

Rig lifecycle

State values

List rigs

Stop a running rig

Start a stopped rig

Delete a rig

End-to-end example

Next steps

Create a rig

SSH and connect

Rig configuration reference

​State values

​List rigs

​Stop a running rig

​Start a stopped rig

​Delete a rig

​End-to-end example

​Next steps

Create a rig

SSH and connect

Rig configuration reference

State values

List rigs

Stop a running rig

Start a stopped rig

Delete a rig

End-to-end example

Next steps