crabbox/docs/features/README.md

Features

Feature docs explain what Crabbox can do and how the pieces fit together. Command syntax lives in ../commands/README.md.

Read when:

• you want a capability overview;
• you are deciding where a behavior belongs;
• you need the feature-level contract before changing code.

Foundations

• Configuration: precedence, YAML schema, profiles, classes, env vars.
• Identifiers: lease IDs, slugs, run IDs, claims, and how lookup resolves.
• Doctor checks: what crabbox doctor validates and how to extend it.
• Network and reachability: --network auto|tailscale|public, port fallback, public/tailnet planes.
• Lease capabilities: --desktop, --browser, and --code selection rules.
• Environment forwarding: name-based env allowlist for the remote command.

Brokered fleet

• Coordinator: brokered leases through Cloudflare Workers and Durable Objects.
• Browser portal: authenticated lease/run UI, detail pages, bridge routes, and runner visibility.
• Broker auth and routing: GitHub login, shared bearer tokens, optional Cloudflare Access, and Worker routes.
• Auth and admin: login/logout/whoami and trusted operator controls.
• Telemetry: lightweight Linux load, memory, disk, uptime, and run resource samples.
• History and logs: coordinator run records, events, and retained remote output.
• Cost and usage: guardrails, provider-backed pricing, and reporting.
• Lifecycle cleanup: release, expiry, keep mode, and direct cleanup.

Providers

• Providers: provider overview, target matrix, classes, and fallback.
• Capacity and fallback: class chains, market spot/on-demand, region/AZ routing.
• Provider backends: contract reference for backend interfaces and registration.
• Authoring a provider: step-by-step guide to writing a new provider.
• AWS: EC2 Linux, Windows, WSL2, EC2 Mac, capacity, AMIs, and security groups.
• Azure: Azure Linux/native Windows, shared infra, capacity, and cleanup.
• Hetzner: Linux-only managed Hetzner behavior, classes, and cleanup.
• Blacksmith Testbox: delegated Testbox backend behavior.
• Daytona: Daytona SDK/toolbox sandbox leases with optional short-lived SSH access.
• Islo: delegated Islo sandbox runs using the Islo Go SDK.

Runners and reachability

• Tailscale: optional tailnet reachability for managed Linux leases and static hosts.
• Mediated egress: browser/app egress through an operator machine using the Cloudflare Worker mediator.
• Runner bootstrap: cloud-init, installed tools, SSH port, and readiness.
• Prebaked runner images: provider-owned image storage and the image/cache/state boundary.
• Image bake runbook: exact AWS bake, candidate smoke, promotion, rollback, and cleanup flow.
• SSH keys: per-lease keys, provider key cleanup, and local storage.

Sync, run, and recording

• Sync: Git file-list manifests, rsync, fingerprints, excludes, guardrails, and sanity checks.
• Actions hydration: let GitHub Actions prepare a runner, then sync local work into that workspace.
• Interactive desktop and VNC: VNC hub, support matrix, tunnel model, and QA boundaries.
• Artifacts: screenshots, video, trimmed GIFs, logs, metadata, templates, and PR publishing.
• Linux VNC, Windows VNC, macOS VNC: OS-specific desktop setup and troubleshooting.
• Test results: JUnit summaries attached to recorded runs.
• Cache controls: inspect, purge, and warm remote package/build caches.

Integrations

• OpenClaw plugin: agent tools that wrap the CLI.
• Repository onboarding: crabbox init, repo config, workflow stub, and agent skill.
• Source map: implementation files behind documented behavior.

Command docs

• doctor
• init
• warmup
• run
• history
• logs
• results
• artifacts
• cache
• status
• list
• usage
• ssh
• vnc
• inspect
• stop
• actions
• cleanup
• config
• login
• logout
• whoami
• admin