toolsdevopsai

Start here

This is a lookup page, not a system tour. For the architecture, trust boundary, and Studio provider setup, read Crabbox on qs-mac-studio. This page is for the moment when you already know you need a box and want the exact command shape.

The recurring placeholder is BOX, a shell variable containing the box slug:

BOX="$(just crabbox ensure)"

Once you have a slug, keep using it explicitly. That single habit avoids most confusing Crabbox behavior when more than one box is live.

Key Takeaway

If a command accepts --id, pass the slug. A warm box is only reused when Crabbox knows which box you mean.

Setup and health

Command Use it when Notes
crabbox config path You need to inspect or edit trusted user config. On macOS, this usually points under ~/Library/Application Support/crabbox/.
crabbox doctor You want to verify the provider, config, SSH path, and permissions. Treat this as the real setup gate; every check should read ok.

Common setup misses show up here first: loose config-file permissions, missing trustProviderOutput, bad SSH access to qs-mac-studio, or a provider path that is not absolute.

Creating and finding boxes

Command Use it when Output
just crabbox ensure You want a ready box and do not care whether it is reused or newly warmed. Prints the slug.
crabbox warmup You deliberately want to lease a fresh box. Prints lease details, including the slug.
crabbox list You need to see live boxes and pick a target. Shows slugs and status.

For normal day-to-day work, start with the helper:

BOX="$(just crabbox ensure)"
echo "$BOX"

If you intentionally need a fresh lease, capture the slug from warmup instead:

BOX="$(crabbox warmup | grep -oE 'slug=[a-z-]+' | head -1 | cut -d= -f2)"

Running commands

The reusable form is always:

crabbox run --id "$BOX" -- <command>

Common Osprey examples:

Command What it does Box type
crabbox run --id "$BOX" -- just api generate Regenerates gqlgen output such as generated.go and models_gen.go. Plain or privileged
crabbox run --id "$BOX" -- just api test Runs Go unit tests only. Plain or privileged
crabbox run --id "$BOX" -- just api check Runs the full Go quality gate: codegen, fmt, lint, unit tests, coverage. Plain or privileged
crabbox run --id "$BOX" -- just mcp check Runs the MCP quality gate. Plain or privileged
crabbox run --id "$BOX" -- just dev-headless Starts Postgres, Keycloak, nginx, API, and web inside the box. Privileged

On a fresh or freshly synced box, run codegen before just api test if you are not using just api check:

crabbox run --id "$BOX" -- bash -lc "just api generate && just api test-integration"

That chained form matters for integration tests because generated files are gitignored and can disappear during sync.

Warning

A bare crabbox run -- <command> is intentionally different: it leases a temporary box, runs once, then destroys it. That is fine for one-shot work, but wasteful when you expected to reuse dependencies and generated files.

App work, screenshots, and tunnels

App work starts by ensuring the box was created with privileged mode enabled in trusted config. Changing privileged: true after a box already exists does not mutate that box; release the old slug and ensure a new one.

crabbox release --id "$BOX"
BOX="$(just crabbox ensure)"
crabbox run --id "$BOX" -- just dev-headless

Use screenshots when you need inspectable proof without opening a browser:

Command What it captures
just crabbox screenshot /admin/tenants Screenshots a path, auto-selecting the box only when exactly one is ready.
just crabbox screenshot eco-list "$BOX" Runs a named screenshot scenario against the explicit box.

Use a tunnel when a human needs to browse the app:

just crabbox app-tunnel "$BOX"
# open http://localhost:4700
# Keycloak forwards at http://localhost:4710

Local tunnel ports point at one selected box. If 4700 or 4710 is already occupied by local dev, stop that process before opening the tunnel.

Teardown and cleanup

Command Use it when Notes
crabbox ssh --id "$BOX" You need an interactive shell inside the box. Useful for direct inspection; avoid making hidden state you cannot reproduce.
crabbox release --id "$BOX" You are done with a specific box. This is the normal resource-return command.
crabbox cleanup You want to sweep expired or orphaned containers. Leaves healthy warm boxes alone.

Confirm teardown when resources matter:

crabbox release --id "$BOX"
crabbox list

The most common misleading failure is lease <id> claim changed; retry, usually after crabbox warmup. Re-run the command. The most common real failure is forgetting --id, using a non-privileged box for full-stack work, or running just api test before regenerated gqlgen files exist.

  1. Find the slug first - capture it with BOX="$(just crabbox ensure)" or choose it from crabbox list.
  2. Reuse explicitly - pass --id "$BOX" on runs, SSH, and release.
  3. Generate before narrow tests - fresh boxes need gqlgen output before just api test.
  4. Use privileged boxes for app stacks - just dev-headless and Docker-in-Docker integration work need that mode at box creation time.
  5. Release what you lease - cleanup and the Studio reaper are safety nets, not the main lifecycle.

Discussion Prompts

  • Which of these commands should become the default checklist in PR verification comments?
  • Should app-box and plain-gate-box setup be split into two named local config profiles?
  • Which screenshot scenarios are common enough to deserve stable names?

References

  1. Crabbox on qs-mac-studio - The companion overview for the Studio provider, trust boundary, lifecycle, and interaction levels.
  2. OpenClaw Crabbox - The Crabbox CLI and provider framework behind these commands.