Start

Concepts

Concepts

Crabbox supplies on-demand computers for agents and humans. You edit locally; a lease reserves a box, and a run syncs the working tree and executes a command there. Separate remote boxes let agents run tests and builds in parallel without sharing a laptop's CPU, memory, or service ports.

Providers supply Linux, macOS, native Windows, and WSL2 targets. A warm lease keeps setup available between runs. Desktop, browser, and Code capabilities add interactive access; the coordinator portal shows shared leases and run evidence. See the access guide for those surfaces.

This glossary defines the terms used across the CLI, coordinator, and docs. When two synonyms exist, the preferred form is in bold.

#Compute vocabulary

Lease - a time-bounded reservation of a remote runner that Crabbox created or resolved. Has a canonical ID (cbx_...), a friendly slug, an idle timeout, a TTL, and a state (active, released, expired, failed). Leases are the unit of cost accounting and cleanup.

Runner - the remote machine itself. Provisioned by the provider, prepared by the bootstrap step, and used for one or more runs. Crabbox does not distinguish between a Hetzner cloud server, an AWS EC2 instance, and a static SSH host beyond what the provider backend reports; all are runners.

Box / testbox - informal synonym for runner, used in the README and some feature docs. Prefer "runner" in new docs unless the surrounding context talks about leases as a product, in which case "box" reads more naturally (for example "warm box").

Pool - the set of currently active runners visible to a user, org, or the whole fleet. crabbox list and the admin GET /v1/pool endpoint both expose it.

Pond - an emergent peer group of leases that share a pond=<name> provider label. A pond is not a central cluster object; it exists for as long as at least one active lease carries the label. Use crabbox pond peers, crabbox pond connect/disconnect, and crabbox pond release to operate on the group. See Pond.

Lease ID - the canonical machine-friendly identifier, cbx_ plus 12 lowercase hex characters (16 characters total, e.g. cbx_abcdef123456). Used in labels, logs, claims, and broker APIs. See Identifiers.

Slug - a friendly lease name. New automatically allocated slugs combine a wordlist pair and an eight-hex ID fingerprint, such as swift-crab-1f3a9c2b; collision handling can append another four-hex suffix. Custom names such as --slug swift-crab remain available. A requested --slug is normalized to [a-z0-9-] (max 41 chars). Most commands accept either the ID or the slug via --id.

Run - a single crabbox run invocation with a run_ ID, lease, command, and exit code. Coordinator-backed runs also have durable run history; direct runs use their IDs in local timing, proof, and failure artifacts. See History and logs.

Workspace - the repo checkout plus runtime state inside a lease or delegated sandbox: synced files, hydrated dependencies, the provider-owned working directory, command output, and optional desktop/browser state. Prefer "workspace" when the user-visible product is more than the raw runner.

#Roles

CLI - the local Go binary crabbox. Owns config, sync, command execution, output streaming, and per-lease SSH keys. See Architecture.

Broker / coordinator - the authenticated shared control plane. It owns provider credentials, lease state, expiry, cleanup scheduling, run history, usage, and cost caps. It runs on Cloudflare Workers with a Fleet Durable Object or on Node.js with PostgreSQL and pg-boss. The two terms are interchangeable; "coordinator" is preferred in docs that emphasize the service, "broker" when emphasizing the trust boundary between the CLI and the provider.

Provider - a Crabbox adapter that knows how to acquire, resolve, list, and release runners on a backing service. Crabbox ships adapters for managed clouds (AWS, Azure, Google Cloud, Hetzner), self-hosted and local hosts (Proxmox, Parallels, Local Container, static SSH), managed dev sandboxes reached over SSH (Daytona, KubeVirt, External, Namespace Devbox, Semaphore, Sprites, exe.dev, RunPod, Railway), and delegated execution sandboxes (Blacksmith Testbox, E2B, Modal, Islo, Tensorlake, Upstash Box, Cloudflare, Azure Dynamic Sessions, W&B). See the Provider reference.

Backend - the Go interface a provider implements: SSHLeaseBackend for providers that hand Crabbox a real SSH target it provisions and connects to, and DelegatedRunBackend for providers that own command execution themselves. See Provider backends.

Operator - a person with broker-side access (admin token, Cloudflare config). Operators run crabbox admin commands and image bake/promote flows.

Agent - an LLM-backed process invoking Crabbox through the CLI. Agents are first-class users of Crabbox; the docs are written for both humans and agents. Crabbox supplies execution and evidence; the agent or its harness owns prompts, decisions, and orchestration. Repository config and workloads must be trusted.

#Modes

Brokered mode / coordinator mode - the path where the CLI talks to the coordinator for lease creation, state, and cleanup, while still doing SSH, rsync, and command execution directly to the runner. Provider secrets stay coordinator-side. Chosen when the provider supports the coordinator (AWS, Azure, Daytona, Google Cloud, Hetzner) and a broker URL is configured via CRABBOX_COORDINATOR or config set-broker.

Direct mode / direct-provider mode - the CLI talks straight to the provider API with no broker, no central run history, and no spend caps. This is the only mode for every provider outside the brokerable five, and the fallback for those five when no broker URL is configured.

Static mode - lease behavior for provider: ssh. The host is operator-owned; Crabbox neither provisions nor deletes it. Always direct, never brokered.

Delegated mode - the path used by delegated-run providers (Blacksmith, E2B, Modal, Islo, and others). The provider owns command execution and streams output back to Crabbox. Crabbox-owned local sync options (--sync-only, --checksum) are rejected; sync timing reports sync=delegated.

#Commands

warmup - acquire a lease and keep it ready (--keep, default true). No command runs yet; the result is a warm box awaiting work.

run - acquire or reuse a lease, sync the checkout, run a command, stream output, and return the exit code. By default, newly acquired leases are released and explicitly reused leases stay available; --keep and --stop-after control that policy.

stop / release - end a lease using the provider's cleanup contract. Disposable resources are normally deleted; static hosts and provider-specific retained resources are exceptions.

cleanup - sweep eligible direct-provider leftovers after verifying exact ownership. A label, name, or ID alone never authorizes deletion.

reuse - using --id (or a slug) to pick an existing lease instead of creating a new one for run. warmup creates a lease; --lease-id is an idempotent creation contract on supporting providers, not a general reuse flag.

reclaim - move a local claim from one repo checkout to another so a lease created in repo A can be reused from repo B (--reclaim). Required because Crabbox binds leases to repos by default.

hydrate - prepare a runner with project dependencies from a repo-owned GitHub Actions workflow. The default path executes supported setup steps; the --github-runner fallback registers the box as a self-hosted runner and dispatches a real Actions job when full GitHub semantics are required. See Actions hydration.

#State

Idle timeout - how long a lease may go without a heartbeat before the broker auto-releases it. Default 1800s (30m). Reset by every heartbeat or explicit touch.

TTL - the total wall-clock lifetime from creation. Default 1800s (30m), with a default maximum of 14400s (4h). Owners can request bounded extension with crabbox extend; command-running heartbeats can auto-extend when policy and the provider lifetime capability allow it. Plain heartbeats only refresh idle time. expiresAt = min(createdAt + min(ttl, currentMaxTTL), lastTouchedAt + idleTimeout). Policy tightening also applies to existing live leases.

Heartbeat - a POST /v1/leases/{id}/heartbeat call sent by the CLI during long-running commands. Bumps lastTouchedAt, can ship telemetry samples, and can update the idle timeout when explicitly requested. Heartbeats at or after expiresAt are rejected; once the deadline passes, cleanup owns the lease.

Touch - lower-level synonym for "update lease state and idle". The provider's Touch method handles direct-provider state updates; the heartbeat is the brokered equivalent.

Reserved cost - the worst-case TTL cost the broker reserves for a lease at creation time (hourlyRate × ttl). Charged against the monthly spend cap until the lease ends; freed on release.

Estimated cost - elapsed-runtime cost for a lease, computed from the hourly rate and time spent active. What crabbox usage reports as a billing approximation. See Cost and usage.

#Sync

Manifest - the NUL-delimited list of paths Crabbox will sync, built from git ls-files --cached plus git ls-files --others --exclude-standard, with deletions tracked separately.

Fingerprint - a hash of the commit, dirty file metadata, and manifest. When the local fingerprint matches the remote one, Crabbox skips rsync entirely.

Git seeding - the optional first-sync step where Crabbox fetches the configured origin/base ref into the runner's Git directory before rsync, so changed-file diffs are available remotely.

Base ref - the Git ref Crabbox seeds and hydrates against. Configurable per repo via sync.baseRef.

Sanity check - a guardrail run after rsync that detects mass tracked deletions, missing manifest entries, and other suspicious sync outcomes. See Sync.

#Capabilities

Desktop - lease capability (--desktop) that adds a visible session: resize-capable TigerVNC + XFCE on managed cloud Linux and new local containers, or Wayland/GNOME. Required for crabbox vnc, crabbox webvnc, and most --browser UI runs.

Browser - lease capability (--browser) that installs or discovers a supported browser and exports its path. It can run headless without a desktop; add --desktop for visible testing. The engine depends on the provider/image, and a logged-in profile is not supplied.

Code - lease capability (--code) that installs code-server bound to loopback (port 8080). Used by crabbox code and the portal /code/ bridge; managed Linux only.

Tailscale - optional reachability layer for managed Linux leases. Joins the lease to the configured tailnet so clients can reach the runner without its public IP. Distinct from the network mode (--network tailscale) that selects which plane the CLI uses. See Capabilities.

#Coordinator Runtime

FleetCoordinator - the runtime-neutral TypeScript control-plane behavior. Both deployment runtimes use the same routes, auth, provider adapters, records, cost controls, cleanup rules, portal, and bridge protocols.

Durable Object - the Cloudflare primitive that stores coordinator state and serializes fleet decisions. Crabbox uses one Fleet Durable Object (idFromName("default")) in the Cloudflare runtime.

PostgreSQL runtime - the portable Node.js deployment. The crabbox schema stores coordinator key/value records; pg-boss uses crabbox_jobs for exact maintenance jobs and periodic reconciliation.

Alarm - a future cleanup deadline. Cloudflare uses Durable Object alarms; Node/PostgreSQL uses pg-boss jobs. Both schedule idle-timeout, TTL, cleanup retry, and provider maintenance work.

Portal - the server-rendered, authenticated web UI hosted by the coordinator under /portal/.... Surfaces lease detail, run logs and events, and the live VNC/Code panes. See Browser portal.

Bridge - a connection through the coordinator to a local CLI relay. WebVNC and Code relays maintain SSH tunnels to runner loopback services (VNC on 5900, code-server on 8080); they must stay running while the browser is connected. Egress uses a separate ticketed relay. The coordinator authenticates access and does not open SSH connections itself.

#Identity

Owner - the identity that owns a lease. GitHub login binds the immutable github:<numeric-id> account identity. Shared-token automation uses the configured owner or Git email, subject to verified identity routing; see Operational security.

Org - the GitHub-style organization namespace for a lease. Resolved from the signed token or CRABBOX_ORG. Used for usage scoping and multi-tenant cost caps.

Allowed org - the GitHub org membership the broker requires before issuing a signed login token. Configured per Worker.

Admin token - the separately scoped token required for GET /v1/pool, admin lease routes, and fleet-wide listing. Held more closely than the shared automation token.

Cloudflare Access - optional protection layer in front of the Worker. When configured, the Worker trusts the verified cf-access-jwt-assertion header for identity instead of raw client headers.

#Storage

State directory - where the CLI keeps local claims, history and checkpoints. An explicit XDG_STATE_HOME puts these under $XDG_STATE_HOME/crabbox and also selects that namespace for generated per-lease keys and host trust. When unset or empty, state uses <os-user-config-dir>/crabbox/state, while keys retain <os-user-config-dir>/crabbox/testboxes. Changing roots does not migrate or search old state. See SSH keys.

Claim - a JSON file under the state directory binding a lease to a repo checkout. Required for crabbox run --id to resolve slugs and to refuse cross-repo reuse without --reclaim.

Workdir / work root - the directory on the runner where Crabbox syncs the repo. Default /work/crabbox on Linux; provider- and target-specific on Windows (C:\crabbox in normal mode) and macOS.

#Evidence and artifacts

Run history - the broker's record of past runs (crabbox history, logs, events, results). Distinct from a lease's live state. See History and logs.

Test results - parsed JUnit outcomes for a recorded run, surfaced by crabbox results <run-id> (suites, tests, failures, errors, skipped). See Test results.

Telemetry - lightweight Linux host-health samples (load, memory, disk, uptime) captured around a run. Per-run resource snapshots, not product analytics. See Telemetry.

Artifacts - QA output bundles produced by crabbox artifacts (screenshots, video, GIF, logs, status, metadata) that can be published and commented on a PR. See Artifacts.

Egress - mediated outbound network for a lease: crabbox egress bridges the box's traffic through the operator's machine over a WebSocket. See Egress.

Checkpoint - saved VM-or-workspace state you can restore or fork from, with IDs chk_.... Kinds include workspace archives, recipes, and provider-native snapshots/images. See Checkpoints.

Cache volume - provider-backed persistent mount point for speed-only state, keyed by repo/runtime/platform inputs and mounted at an absolute cache path. Unlike a checkpoint, it is not a forkable scenario handle and the worktree remains the source of truth. See Cache Controls.

Capsule - a portable, replayable failure bundle captured from a GitHub Actions run (crabbox capsule from-actions) and re-run with crabbox capsule replay. See Capsules.

#Documentation

Source map - the doc page that points each user-visible behavior at the implementation file behind it. See Source map.

Feature page - a doc under docs/features/<name>.md describing one capability area. Owns the conceptual story; commands and providers cross-link from here.

Command page - a doc under docs/commands/<name>.md describing the flags, behavior, and exit codes of one CLI command, kept in sync with --help.

Provider page - a doc under docs/providers/<name>.md describing one provider's targets, config keys, env vars, sync behavior, and expected failures.

Related docs: