Features

Features

GitHub Edit page

Features

Feature docs explain what Crabbox can do and how the pieces fit together. They cover the capability-level contract — what a feature is, when it applies, and how the parts interact. Command syntax and per-flag reference live 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

#Coordinator and brokered fleet

  • 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.
  • Lifecycle cleanup: release, expiry, keep mode, and direct cleanup.

#Providers

  • Providers: provider overview, target matrix, classes, and fallback.
  • Provider reference: per-adapter pages for every registered provider.
  • Capacity and fallback: class chains, market spot/on-demand, and region/AZ routing.
  • Provider backends: contract reference for backend interfaces and registration.
  • Authoring a provider: step-by-step guide to writing a new provider.
  • XCP-ng: direct XCP-ng provider on dedicated x86_64 pool hardware. XCP-ng itself can host Linux, Windows, and BSD guests; Crabbox normal leases use Linux templates, with separate Windows x86_64/x64 ISO E2E coverage.
  • Incus local E2E testbed: local Apple Silicon runbook and smoke contract for the future incus adapter.

Provider deep-dives that live here in features/:

  • AWS: EC2 Linux, Windows, WSL2, EC2 Mac, capacity, AMIs, and security groups.
  • Azure: Azure Linux, Windows, WSL2, shared infra, capacity, and cleanup.
  • Hetzner: Linux-only managed Hetzner behavior, classes, and cleanup.
  • Blacksmith Testbox: delegated Testbox runner behavior.
  • Namespace Devbox: Namespace Devbox SSH leases with Crabbox sync/run.
  • Namespace Devbox setup: CLI install, browser authentication, and live checks.
  • Namespace Compute Instance: disposable Linux Compute leases through nsc.
  • Semaphore: Semaphore CI job leases with Crabbox SSH sync/run.
  • Sprites: Sprites microVM SSH leases through sprite proxy.
  • Daytona: Daytona SDK/toolbox sandbox leases with optional short-lived SSH access.
  • Islo: delegated Islo sandbox runs using the Islo Go SDK.
  • E2B: delegated E2B sandbox runs using the E2B sandbox APIs.

#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.
  • 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.
  • Jobs: named repo-local warmup, hydrate, run, and cleanup workflows.
  • 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.
  • 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.
  • Cache volumes: provider-backed persistent cache mounts for rebuildable speed state.

#Integrations

#Command docs

#Setup and configuration

  • init — initialize repo config
  • login — authenticate with broker
  • logout — clear broker token
  • whoami — show authenticated user
  • config — show merged config
  • doctor — validate prerequisites

#Lease lifecycle

  • warmup — provision a warm box
  • run — sync and run a command
  • job — run a named repo job
  • status — show lease status
  • list — list active leases
  • stop — release a lease
  • cleanup — clean up stale leases

#Workspace management

  • sync-plan — preview the sync manifest
  • actions — hydrate from repo workflow setup
  • capsule — capture/replay Actions failures
  • checkpoint — snapshot/restore/fork workspaces
  • cache — manage remote caches
  • image — manage provider images

#Run observation

  • history — list run history
  • logs — show run logs
  • events — show run events
  • attach — attach to an active run
  • results — show test results
  • artifacts — manage run artifacts
  • media — capture screenshots/video

#Interactive access

  • ssh — SSH to a lease
  • desktop — desktop/input commands
  • vnc — native VNC access
  • webvnc — browser-based VNC
  • code — code-server access
  • screenshot — capture screenshots
  • egress — mediated egress proxy

#Pond and collaboration

  • pond — peer discovery and lifecycle across a lease group
  • share — share lease access
  • unshare — revoke shared access

#Operations

  • inspect — detailed lease info
  • providers — show the provider capability matrix
  • usage — cost and usage reports
  • admin — admin operations
  • azure — Azure-specific commands