Pond - Crabbox Docs

Crabbox Remote testbox docs

Search docs

Pond

A pond is a lightweight way to group related leases, discover how to reach each one, and release them together. It is not a central cluster object: a pond is an emergent set of active leases that share the reserved pond= provider label, plus local claim sidecars for providers that do not own cloud labels. A pond exists for as long as at least one active lease carries the label.

Reachability between pond members depends on the transport plane each member's provider supports. Tailscale gives true peer-to-peer .cbx names; the URL bridge gives provider-native HTTP(S) endpoints; the SSH-mesh gives operator-side ssh -L forwards. A pond can mix providers and planes.

A --pond of one is the default — single-box flows are unchanged.

> Preview. Pond is preview for v0.x. The reserved pond= label key is > intended to stay, but metadata shape and command flags may evolve before v1.0.

#Quick start

# Lease a few members into one pond (slug = stable role name).<br>crabbox warmup --pond pr-42 --slug api --provider hetzner --tailscale<br>crabbox warmup --pond pr-42 --slug db --provider hetzner --tailscale

# Discover peers, run work against a member, then tear the pond down.<br>crabbox pond peers --pond pr-42<br>crabbox run --id api -- "DB_HOST=db.cbx go test ./..."<br>crabbox pond release pr-42<br>Use --slug as the stable role name; it is what shows up in discovery and in .cbx names. Whether that slug is directly dialable from another member depends on the transport plane (see below).

#Naming a pond

--pond accepts any string and normalizes it: lowercased, characters outside [a-z0-9-] collapsed to -, runs collapsed, leading/trailing dashes trimmed. The normalized name must contain at least one letter or digit and be at most 41 characters. The same name is reused everywhere the pond appears (the label value, the Tailscale ACL tag, peer hostnames), so it stays in a regular DNS-like identifier space.

#The three transport planes

Each provider self-declares which planes its leases can serve via its Spec().Features (FeatureTailscale, FeatureURLBridge, FeatureSSH). A single provider can advertise more than one — for example a direct Hetzner box advertises both Tailscale and SSH, so Tailscale is the preferred peer mesh while pond connect can still build operator-side SSH forwards. URL-only sandboxes (such as Islo or E2B) do not join the peer mesh; they surface HTTP(S) endpoints instead.

PlaneFeature flagProviders that advertise it (today)What you getTailscaleFeatureTailscaleHetzner, Azure, GCPtrue peer-to-peer mesh, .cbx DNSBridgeFeatureURLBridgeIslo, E2B, Modal, Cloudflare, Tensorlake (adapters report unsupported until they ship a per-sandbox HTTPS ingress)provider-native HTTP(S) endpoints for discovery and sharingSSH-meshFeatureSSHany provider advertising SSH: Hetzner, Azure, GCP, AWS, Proxmox, static ssh, RunPod, exe-dev, Daytona, Sprites, Namespace, Semaphore, local-container, Parallelsoperator-side ssh -L tunnels via pond connect<br>macOS and Windows peer reachability are not covered by any plane yet.

Capabilities are derived from each provider's FeatureSet, not from a static table — a provider opts into a plane by declaring the feature. See providers.md for the full capability matrix and tailscale.md for the Tailscale transport.

#Commands

crabbox warmup --pond NAME --slug ROLE --provider PROVIDER [--tailscale] [--expose PORT]...<br>crabbox run --id LEASE_OR_SLUG -- COMMAND<br>crabbox list --pond NAME<br>crabbox doctor --pond NAME

crabbox pond peers --pond NAME [--provider P] [--share-port PORT] [--share-ttl D] [--json]<br>crabbox pond connect NAME [--provider P] [--export] [--json]<br>crabbox pond disconnect NAME<br>crabbox pond release NAME<br>#pond peers

Lists every member of the pond, regardless of provider. --pond is required. With no --provider, the resolver fans out across every provider represented in the pond and concatenates the result; pass --provider P to restrict to one.

Each row carries a primary transport hint plus the full transports list of every plane that member's provider supports:

// crabbox pond peers --pond pr-42 --json -> { "members": [ ... ] }<br>"slug": "api",<br>"leaseID": "cbx_0a1b2c3d4e5f",<br>"provider": "hetzner",<br>"pond": "pr-42",<br>"transport": "tailnet", // primary / recommended plane<br>"transports": ["tailnet", "ssh"], // every plane this provider supports<br>"endpoint": "100.64.1.3"<br>The endpoint shape depends on the primary plane: a tailnet IPv4/FQDN for Tailscale members, ssh://host:port for SSH-lease members, and a per-port HTTPS URL for URL-bridge members. Members whose endpoint is not yet recorded surface with transport: "pending" and an honest note; providers with no networking adapter (e.g. Blacksmith) surface with transport: "none".

The bridge plane is HTTP-only by design. For URL-bridge providers you can publish a per-peer public URL for a port:

crabbox pond peers --pond pr-42 --provider islo --share-port 8080 --share-ttl 12h --json<br>--share-port is...