serve
Donate spare container capacity to the configured coordinator using the existing broker login. See the provider reference for owner-only placement, security, sizing, cache volumes, and network requirements.
crabbox serve --cpus 24 --memory 48g
crabbox serve --runtime podman --cpus 8 --memory 16g --advertise-address 100.64.1.2
crabbox serve machines --json
crabbox serve status --json
crabbox serve status --probe --json
crabbox serve cache prune
crabbox serve install --cpus 24 --memory 48g
crabbox serve uninstall
| Agent flag | Meaning |
|---|---|
--cpus | Offered CPU count; defaults to host logical CPUs |
--memory | Required offered memory; MiB integer, m, or g suffix |
--max-leases | Maximum concurrent containers, default 8, maximum 32 |
--name | Machine display name; default hostname |
--advertise-address | Repeatable client-reachable IPv4 (max 4); replaces automatic tailnet and LAN candidates |
--no-lan-candidates | Disable automatic private LAN candidates |
--ssh-port | Agent SSH front-door port, 1–65535; default 2222 |
--runtime | docker or podman |
--poll-interval | Minimum poll and heartbeat-response spacing, 500ms–10s; default 2s |
--state-dir | Private machine identity/status directory |
--no-cache-volumes | Disable managed cache volumes |
--drain-on-exit | Remove containers on orderly agent shutdown |
--availability | auto (default) or always to disable availability gating |
--max-host-cpu | Maximum non-serve host CPU fraction, default 0.5 |
--require-user-idle | Minimum console idle duration, default 0 on desktops or 10m on laptops |
--require-ac-power | Require AC on laptops, default true; ignored on desktops |
--max-memory-pressure | Busy at warn or critical, default critical |
--probe | Read-only local availability sampling (status only); no coordinator needed |
--probe-duration | Probe observation period, 1m–1h, default 7m |
CRABBOX_SERVE_MEMORY supplies the memory default. serve.advertiseAddresses or comma-separated CRABBOX_SERVE_ADVERTISE_ADDRESSES configures explicit addresses; the singular CRABBOX_SERVE_ADVERTISE_ADDRESS remains a fallback. serve.noLANCandidates / CRABBOX_SERVE_NO_LAN_CANDIDATES disables LAN discovery. serve.sshPort and CRABBOX_SERVE_SSH_PORT configure the single SSH front-door port; --ssh-port takes precedence. Allow that one port in the host firewall and tailnet policy when using tailnet routes. LAN routes bypass tailnet policy and expose the key-authenticated front door to the LAN. Containers expose SSH only on loopback. The ordinary broker URL/token configuration still applies; credentials are never printed or written into a service command.
Serve requires coordinator enablement through CRABBOX_SERVE_ALLOWED_OWNERS; unset or empty disables it. Unlisted owners receive serve_not_enabled.
Serve prepares a reusable local image in the background after its first heartbeat and reconciliation to avoid reinstalling bootstrap packages for every lease. See prepared container images for details, fallback behavior, and image evidence.
Each poll starts at least --poll-interval after the prior poll start and heartbeat response.
status checks coordinator access and reads the local machine UUID, last successful coordinator contact, active assignments, caps, draining state, and availability with reasons. machines queries owner-visible coordinator inventory. Both support --json. See availability for signals, configuration, laptop defaults, and hysteresis.
machines also shows each machine's served lease count, runtime, and CPU-hours for leases created in the current UTC month. Completed usage is recorded once when the agent confirms container cleanup; live and pending-cleanup allocations are added from the machine's current lease list. JSON exposes these as usage.month, usage.leases, usage.activeLeases, usage.runtimeSeconds, and usage.cpuSeconds. CPU-hours are runtime multiplied by each lease's assigned CPUs, divided by 3600; they measure allocated capacity, not sampled CPU utilization. Only your machines and usage in the current organization are shown, even for admins. The portal Machines section shows the same totals. Completed-usage rollups start at deployment, with no historical backfill. A lease that crosses a month boundary is attributed to its creation month, including its entire recorded runtime. Use usage with --month YYYY-MM for full recorded history, another month, or historical machine IDs. Machine listings use point reads, not a history scan.
Use CRABBOX_SERVE_AVAILABILITY_DEBUG=1 crabbox serve status --probe --json to diagnose individual signal failures and timeouts on stderr. See availability diagnostics for sampling deadlines and conservative raw-host-CPU fallback behavior.
install writes and loads a per-user LaunchAgent on macOS or a systemd user unit on Linux, preserving the supplied flags. It uses the current executable path and account's existing broker configuration. uninstall unloads and removes that service. Linux user services run while the user manager is active; configure systemd lingering separately if required. Existing service files are never overwritten implicitly. Default shutdown leaves containers until their last deadlines; install with --drain-on-exit for immediate removal on stop.
cache prune requires the same state directory and runtime used by the agent, and exclusive access to its state lock. Stop the agent first. It removes only the named cache volumes derived for that machine and images labeled crabbox.serve.prepared=true that no running container uses. Prepared images may be shared by several agents. Removal is never forced; a runtime refusal is reported. An idle agent whose prepared image was pruned uses its configured image with lease-time bootstrap and starts background re-preparation on its next lease; no agent restart is required.