Create a rig

This guide walks through creating a rig, waiting for it to become ready, and tearing it down. By default everything runs on the hosted platform at app.amika.dev.

Prerequisites

An Amika account. The CLI uses amika auth login. The SDK needs an API key, which you pass as apiKey.
(For the --git flow) Git installed and a repo to mount.
For the SDK: npm install @amika/sdk.

Step 1 — Create the rig

The simplest rig uses the coder preset (Ubuntu 24.04 with Node, Python, and the Claude Code / Codex / OpenCode CLIs pre-installed).

amika rig create --name dev-box --preset coder

import { AmikaClient } from "@amika/sdk";

const client = new AmikaClient({ apiKey: process.env.AMIKA_API_KEY! });

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

curl -X POST https://app.amika.dev/api/v0beta1/rigs \
  -H "Authorization: Bearer $AMIKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "dev-box", "preset": "coder"}'

To clone a repo into the rig, run the CLI from inside that repository or pass --git <path-or-URL>. The SDK accepts a URL through repoUrl.

# Clone the repo in the current directory
amika rig create --name dev-box --preset coder

# Or clone a remote URL
amika rig create --name dev-box --preset coder \
  --git https://github.com/gofixpoint/example-repo.git

const rig = await client.rigs.create({
  name: "dev-box",
  preset: "coder",
  repoUrl: "https://github.com/gofixpoint/example-repo.git",
  branch: "main",
});

curl -X POST https://app.amika.dev/api/v0beta1/rigs \
  -H "Authorization: Bearer $AMIKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "dev-box",
    "preset": "coder",
    "repo_url": "https://github.com/gofixpoint/example-repo.git",
    "branch": "main"
  }'

How the CLI picks a repo

Run amika rig create from 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-git to skip auto-detection and create a repo-less rig — a rig with no repository mounted. This is useful for scratch environments or when you clone repos yourself after connecting.

A repo-less rig still boots a full environment; it just starts without a checked-out repository. Configuration for multi-repo and repo-less rigs is covered in the Repository configuration guide.

Step 2 — Wait until it’s ready

A new rig starts out initializing and becomes running once it’s reachable and its setup has finished.

# `rig create` blocks until the rig is ready — no extra step needed.

// `rigs.create` returns before setup finishes.
// `wait` polls every 3 seconds until the rig is running and setup
// succeeded, for up to 15 minutes.
await rig.wait();

# Create returns 202 before setup finishes. Poll until `status` is
# `running` and `setup_status` is `ok`.
curl https://app.amika.dev/api/v0beta1/rigs/dev-box \
  -H "Authorization: Bearer $AMIKA_API_KEY"

rig.wait() throws an AmikaWaitError if provisioning fails, the setup script fails, or the deadline passes. Its reason field says which. Pass { maxWaitMs } to change the deadline.

Step 3 — Tear it down

When you’re done, delete the rig to free its resources.

amika rig delete dev-box --force

await rig.delete();

// Or, without a fetched rig:
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"

Get started

Rigs (machines)

Agents and sessions

Configuration

Connecting to rigs

Guides for agents

Advanced

Create a rig

Prerequisites

Step 1 — Create the rig

How the CLI picks a repo

Step 2 — Wait until it’s ready

Step 3 — Tear it down

Next steps

Send a message to an agent

Inject credentials

Rig lifecycle

Rig configuration reference

​Prerequisites

​Step 1 — Create the rig

​How the CLI picks a repo

​Step 2 — Wait until it’s ready

​Step 3 — Tear it down

​Next steps

Send a message to an agent

Inject credentials

Rig lifecycle

Rig configuration reference

Prerequisites

Step 1 — Create the rig

How the CLI picks a repo

Step 2 — Wait until it’s ready

Step 3 — Tear it down

Next steps