Provider Reference

Read when:

• choosing a Crabbox provider for a repo or one-off command;
• debugging provider-specific provisioning, sync, or command execution;
• changing provider registration, flags, config, or backend behavior.

#Provider model

Every provider registers a backend with one of three kinds:

• SSH lease — Crabbox provisions or connects to an SSH-reachable box and owns

the full lease lifecycle (warmup, sync, run, ssh, cleanup). Core does the rsync/command execution directly to the box over SSH.

• Delegated run — a sandbox or proof runner. The provider owns sync and

command execution end to end; there is no SSH lease and no local rsync.

• Service control — Crabbox can inspect or stop a provider-owned service,

but cannot execute arbitrary commands there.

SSH-lease providers further differ by how they reach the cloud:

• Brokered cloud — aws, azure, gcp, and hetzner can run through the

Crabbox coordinator on Cloudflare or Node/PostgreSQL. The coordinator owns cloud credentials, cost state, cleanup scheduling, and lease accounting. This is the normal shared-team path. Set with config set-broker and a broker URL (CRABBOX_COORDINATOR).

• Direct cloud — the same four providers without a configured broker, plus

cloud providers that never broker (e.g. digitalocean, linode, vultr, proxmox, hostinger, runpod, namespace-devbox, namespace-instance, semaphore, sprites, exe-dev, daytona, morph). The CLI talks to the provider API itself and cleans up best-effort via provider labels.

• Static SSH — ssh connects to a preexisting machine you supply; no

provisioning, no cleanup.

• Local runtime — local-container starts a labeled Linux container through

a Docker-compatible local runtime (Docker Desktop, OrbStack, Colima), apple-container uses Apple's native container runtime on Apple silicon macOS, apple-vz launches a headless Linux VM through Apple's Virtualization.framework, multipass launches local Ubuntu VMs through Canonical Multipass, tart runs macOS VMs on Apple Silicon via Cirrus Labs tart, and hyperv creates local Windows VMs through Microsoft Hyper-V.

• Delegated sandbox — managed sandbox/proof runners that execute remotely

without an SSH lease (e.g. blaxel, e2b, modal, islo, cloudflare, cloudflare-sandbox, azure-dynamic-sessions, docker-sandbox, smolvm). anthropic-sandbox-runtime is the local macOS/Linux delegated-run exception: Anthropic's srt executes on the current machine while still owning sync/run policy end to end. windows-sandbox is the local Windows delegated-run exception.

Select a provider per command with --provider <name> (env CRABBOX_PROVIDER), or set provider: <name> in config. Provider flags are registered before command parsing, so provider-specific flags work even when that provider is not the default. Most names accept aliases (listed below).

<!-- BEGIN GENERATED PROVIDER MATRIX -->

#Provider decision matrix

This table combines the live provider spec compiled into the CLI with curated selection metadata. Regenerate it with node scripts/generate-provider-matrix.mjs. scripts/check-docs.sh fails when provider registration, metadata, docs paths, or this generated table drift.

Current built-in surface: 68 providers (40 SSH lease, 26 delegated run, 2 service control).

Access terms:

• Crabbox-managed SSH: SSH uses Crabbox's normal client; the sync column shows whether run and sync use that data plane.
• Provider-specific SSH: an adapter-specific login helper, not the normal Crabbox data plane.
• No SSH: the provider owns command execution end to end.

<!-- END GENERATED PROVIDER MATRIX -->

#Notes on families and capabilities

• The Azure family ships two backends: the default VM SSH lease

(provider: azure) and the delegated azure-dynamic-sessions provider (Azure Container Apps dynamic sessions). They share the azure family but are distinct adapters.

• The Cloudflare family ships three delegated backends: cloudflare for

Cloudflare Containers and Linux commands, cloudflare-dynamic-workers for Worker-runtime module execution, and cloudflare-sandbox for Cloudflare Sandbox bridge-backed Linux command execution. They are separate providers with separate runner configs and token env vars.

• Tensorlake is Crabbox's Firecracker-backed delegated provider. The separate

firecracker provider is the self-hosted Linux KVM surface with direct lifecycle, normal Crabbox SSH sync/run, and local artifact cleanup.

• Docker Sandbox is a delegated-run provider driven by the standalone sbx

CLI. It has no aliases, so docker, container, and local-docker remain Local Container aliases.

• OpenSandbox is a delegated-run provider using the OpenSandbox Go SDK for

lifecycle, file upload, and execd command execution. It has no aliases in v1, so osb remains reserved.

• Superserve is a delegated-run provider using Superserve's control plane for

sandbox lifecycle and a sandbox data plane for file upload and command execution. It has no aliases in v1.

• Vercel Sandbox is a delegated-run provider using Vercel's Sandbox SDK bridge

for lifecycle, archive upload, command execution, session handles, and deletion. The sandbox CLI is used only for login/readiness checks and manual debugging because Crabbox does not rely on it as a stable lifecycle JSON contract.

• Anthropic Sandbox Runtime is a local one-shot delegated-run provider driven

by the standalone srt CLI. It has no SSH lease, no persistent lifecycle, and no remote sync surface.

• ASCII Box is an SSH-lease provider. Crabbox uses the documented box --json

CLI for lifecycle/status/delete, then runs normal sync and commands over SSH.

• XCP-ng is a direct SSH-lease provider for a self-hosted XCP-ng pool on

dedicated 64-bit x86 server-class hardware. XCP-ng itself can host Linux, Windows, and BSD guests, but Crabbox's current xcp-ng adapter provisions normal leases from Linux templates only. Crabbox talks to XAPI from the CLI, uses VM.copy plus VM.provision, injects cloud-init through a FAT16 CIDATA config drive, optionally moves all VIFs to the configured network, and uses guest metrics for IPv4 discovery. See the provider page for the separate Windows x86_64/x64 ISO E2E harness, and use the Tart provider on Apple hardware for macOS VM workflows.

• incus is a direct Linux SSH-lease provider that stores Crabbox ownership and

expiry metadata in Incus user.crabbox.* instance config keys. Real Apple Silicon smoke still follows the separate local testbed contract documented on the provider page.

• DigitalOcean is a direct-only Linux Droplet provider. It uses

DIGITALOCEAN_TOKEN, per-lease SSH keys, and Crabbox-owned flat tags; it does not run through the coordinator.

• Linode is a direct-only Linux instance provider. It uses LINODE_TOKEN,

per-lease SSH keys, metadata user-data, optional attachment to an existing firewall, and Crabbox-owned tags; it does not run through the coordinator.

• Vultr is a direct-only Linux instance provider. It uses VULTR_API_KEY,

per-lease SSH keys, cloud-init user data, optional attachment to existing firewall groups and VPCs, and Crabbox-owned tags; it does not run through the coordinator.

• Hostinger is a direct-only Linux VPS provider. Purchases require explicit

opt-in; release stops the VPS but does not cancel its subscription.

• Capability flags (--desktop, --browser, --code, VNC) are validated

against each provider's declared feature set. Among the SSH-lease providers, desktop/browser/code surfaces are richest on aws, azure, hetzner, parallels, ssh, and local-container; multipass exposes local VM SSH and sync only in its first implementation, apple-vz does the same through a local helper and host-local SSH proxy, and most direct sandbox/delegated providers expose ssh and Crabbox sync only.

• Actions runner hydration requires a normal SSH lease on Linux. Use a

Linux-capable SSH-lease provider for that path.

crabbox warmup --provider aws --class beast
crabbox run --provider hetzner -- pnpm test
crabbox run --provider digitalocean --type s-1vcpu-1gb -- pnpm test
crabbox run --provider linode --type g6-standard-1 -- pnpm test
crabbox run --provider vultr --type vc2-1c-1gb -- pnpm test
crabbox doctor --provider hostinger
crabbox run --provider docker -- pnpm test
crabbox run --provider docker-sandbox -- go test ./...
crabbox run --provider apple-vz -- go test ./...
crabbox run --provider multipass -- go test ./...
crabbox run --provider blacksmith-testbox --id tbx_123 -- pnpm test
crabbox run --provider namespace-devbox --id blue-lobster -- pnpm test

#Implementation

Provider implementation lives under internal/providers/<name>; registration is in internal/providers/all/all.go. Command orchestration and the renderer surface stay in internal/cli.

Related docs:

• Provider selection
• Provider backends
• Feature overview
• Source map