openclaw/crabbox
openclaw/crabbox
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 9 Wiki Activity
main
crabbox/docs/getting-started.md
Peter Steinberger f031e9d1aa
docs: expand crabbox user guide
2026-05-07 00:47:41 +01:00

5.7 KiB
Raw Permalink Blame History

Getting Started

Read when:

  • you are new to Crabbox and want a working run in 10 minutes;
  • you are evaluating Crabbox for a repo and want to see the shape;
  • you want a reference for what a typical onboarding looks like.

This is a cookbook, not a reference. It walks through one repo end to end, from install to crabbox run -- pnpm test. For deeper coverage, follow the links in each step.

Step 1. Install

brew install openclaw/tap/crabbox

Verify the install:

crabbox --version
crabbox doctor

crabbox doctor should print ok for tools (git, rsync, ssh, ssh-keygen). It is fine if auth and network are still missing - we set those next.

If you do not have Homebrew, GitHub Releases ship signed tarballs for macOS, Linux, and Windows. Download the matching archive from https://github.com/openclaw/crabbox/releases.

Step 2. Log In

crabbox login

login opens a browser to the GitHub OAuth flow. The broker exchanges the OAuth code, verifies your GitHub org membership, and writes a signed token to your user config. From then on, every crabbox command authenticates automatically.

crabbox whoami

Confirms the resolved owner, org, broker URL, and selected provider.

If you are running Crabbox in a CI environment that cannot open a browser, use shared-token auth:

printf '%s' "$TOKEN" | crabbox login \
  --url https://crabbox.openclaw.ai \
  --provider aws \
  --token-stdin

See Auth and admin for the full identity model.

Step 3. Onboard A Repo

Inside the repo:

crabbox init

init writes three files:

.crabbox.yaml                          repo defaults (profile, class, sync, env)
.github/workflows/crabbox.yml          Actions hydration stub (optional)
.agents/skills/crabbox/SKILL.md        agent-facing skill instructions

Open .crabbox.yaml and fill in:

  • profile: a name for this lane (e.g. project-check);
  • class: standard, fast, large, or beast;
  • sync.exclude: directories that should not be sent to the runner;
  • env.allow: env vars the remote command should see.

Then run:

crabbox sync-plan

sync-plan previews what would be sent: file count, total bytes, the biggest files. If it shows surprises (a dist/ folder, a .cache/ you forgot, a 2 GiB asset), tighten sync.exclude and re-run. The first sync to a fresh runner is bound by this size.

Step 4. Warm A Box

crabbox warmup

Warmup acquires a lease through the broker, provisions the runner, bootstraps SSH and tooling, and prints a slug + lease ID:

leased cbx_abcdef123456 slug=blue-lobster provider=aws server=i-0123 type=c7a.48xlarge ip=203.0.113.10 idle_timeout=30m0s expires=2026-05-07T17:30:00Z

The lease is now waiting for commands. Idle timeout (default 30m) and TTL (default 90m) bound how long it lives before the broker reclaims it.

Step 5. Run A Command

crabbox run --id blue-lobster -- pnpm test

What happens:

  1. The CLI verifies SSH readiness on the lease.
  2. It seeds remote Git from your origin/base ref, then rsyncs the dirty working tree.
  3. It runs the command over SSH, streaming stdout/stderr.
  4. It heartbeats the broker so the lease does not idle out mid-test.
  5. It records a run_... history entry with sync time, command time, exit code, and (for Linux) bounded telemetry samples.

You can omit --id for a one-shot run:

crabbox run -- pnpm test

That acquires a fresh lease, runs the command, and releases the lease when the command exits. Use this for ad-hoc tests; use warmup + --id for iterative work.

Step 6. Inspect History

crabbox history
crabbox events run_abcdef123456
crabbox logs run_abcdef123456
crabbox results run_abcdef123456

history lists recent runs for the lease or owner. events prints ordered events (lease, sync, command, output chunks, finish). logs returns the retained command output. results parses any JUnit reports the run attached.

/portal/runs/run_abcdef123456 renders the same data as a browser page if you prefer a UI.

Step 7. Stop The Lease

When you are done:

crabbox stop blue-lobster

Stop releases the lease, deletes the provider machine, removes the local claim, and frees reserved cost. If you forget, the broker idle alarm releases the lease automatically.

crabbox cleanup --dry-run

cleanup is a sweep for direct-provider leftovers. It refuses to run when a coordinator is configured because brokered cleanup is the alarm's job.

Common Variations

Use a kept lease across days:

crabbox warmup --idle-timeout 4h --ttl 8h
crabbox run --id blue-lobster -- pnpm test
crabbox run --id blue-lobster -- pnpm bench
crabbox stop blue-lobster

Open a desktop session:

crabbox warmup --desktop
crabbox vnc --id blue-lobster --open

Open a code-server tab:

crabbox warmup --code
crabbox code --id blue-lobster --open

Use a Mac Studio you already own:

# .crabbox.yaml
provider: ssh
target: macos
static:
  host: mac-studio.local
  user: steipete
  port: "22"
  workRoot: /Users/steipete/crabbox

crabbox run -- xcodebuild test

Use AWS instead of the configured default:

crabbox run --provider aws --class beast -- pnpm test

Where To Go Next