README.md

Features

Crabbox features are reusable capability contracts for configuration, fleet control, runner access, synchronization, execution, and evidence. Use this page to understand what Crabbox can do after a provider has supplied the execution target.

Provider choice, direct/coordinator routing, API-key and credential expectations, sandbox/provider behavior, adapter-specific caveats, and the generated provider matrix live in the Provider Reference. Use crabbox providers and crabbox providers recommend to inspect the provider capabilities compiled into your current binary. Exact command syntax and flags live in the Command Reference.

Foundations

• Configuration: precedence, YAML schema, profiles, classes, and 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, and the public/tailnet planes.
• Lease capabilities: --desktop, --browser, and --code selection rules.
• Environment forwarding: name-based env allowlist for the remote command.

Fleet control and coordination

• Runtime adapter stack: compose adapter serve, adapter ingress, and adapter connect behind a fleet UI.
• Coordinator: shared broker behavior across Cloudflare Durable Object and Node.js/PostgreSQL runtimes.
• Portable coordinator: deploy and operate the Node/PostgreSQL runtime on a conventional container platform.
• Bring your own infrastructure: connect a private control plane through generic providers and optional registered mode.
• Browser portal: authenticated lease/run UI, detail pages, bridge routes, and runner visibility.
• Broker auth and routing: GitHub login, shared bearer tokens, trusted proxy identity, optional Cloudflare Access, and public routes.
• Auth and admin: login/logout/whoami and trusted operator controls.
• Telemetry: lightweight Linux load, memory, disk, uptime, and per-run resource samples.
• History and logs: coordinator run records, events, and retained remote output.
• Cost and usage: guardrails, provider-backed pricing, and reporting.
• Marketplace credits gateway: one customer credit balance and smart routing across brokered capacity.
• Lifecycle cleanup: release, expiry, keep mode, and direct cleanup.

Runners and reachability

• Tailscale: optional tailnet reachability for managed Linux leases and static hosts.
• Pond: group related leases and discover their Tailscale, URL bridge, or SSH-mesh reachability.
• Mediated egress: browser/app egress through an operator machine using the coordinator mediator.
• Runner bootstrap: cloud-init, installed tools, SSH port, and readiness.
• Nested execution: WSL2, container engines, prepared KVM hosts, and their conditional boundaries.
• Prebaked runner images: image storage and the image/cache/state boundary.
• Image bake runbook: exact bake, candidate smoke, promotion, rollback, and cleanup flow.
• SSH keys: per-lease keys, cleanup, and local storage.
• SSH lease transport: native-or-rsync copy selection, loopback tunnels, readiness, and credential boundaries.

Sync, execution, and evidence

• Sync: Git file-list manifests, rsync, fingerprints, excludes, guardrails, and sanity checks.
• Jobs: named repo-local warmup, hydrate, run, and cleanup workflows.
• Hermetic agent evidence: repo-local pattern for separate code/test writer contexts, QA arbitration, required artifacts, and Crabbox remote proof collection.
• Deterministic perf evidence: contract for future reproducible metric budgets and perf gate evidence.
• Actions hydration: let GitHub Actions prepare a runner, then sync local work into that workspace.
• Capsules: local-first replay manifests for GitHub Actions failures.
• Checkpoints: save, restore, and fork reusable remote workspaces.
• Editor handoff: prepare a synced lease for an external editor and keep its activity alive.
• 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: Linux desktop setup and troubleshooting.
• Windows VNC: Windows desktop setup and troubleshooting.
• macOS VNC: macOS desktop setup and troubleshooting.
• Test results: JUnit summaries attached to recorded runs.
• Cache controls: inspect, purge, and warm remote package/build caches.
• Cache volumes: provider-backed persistent cache mounts for rebuildable speed state.

Integrations

• Integration catalog: editors, terminal UIs, coding-agent clients, and one-shot harnesses.
• Repository onboarding: crabbox init, repo config, workflow stub, and agent skill.