heartbeat.md

heartbeat

crabbox heartbeat refreshes the idle deadline for one owned lease and prints the resulting lease state. It is intended for external drivers that keep a lease busy over SSH without running commands through crabbox run.

crabbox heartbeat swift-crab
crabbox heartbeat --id swift-crab
crabbox heartbeat --id swift-crab --idle-timeout 90m
crabbox heartbeat --id cbx_abcdef123456 --provider aws --json

Identifying the lease

Supply exactly one identifier, either as the positional argument or with --id; combining the two is a usage error. The identifier accepts a canonical cbx_... lease ID or an active slug. When --provider is omitted, Crabbox uses the same local-claim routing as status and inspect; an explicit provider still wins.

Coordinator and direct-provider behavior

For managed coordinator leases, the command sends exactly one request through the existing lease heartbeat endpoint. The configured owner credentials and provider binding are unchanged, so unknown, unowned, expired, released, or otherwise terminal leases retain the coordinator's normal failure response.

broker.mode: registered has both coordinator and direct-provider expiry state. The command therefore requires the exact direct claim, sends one coordinator heartbeat, and calls the provider's existing Touch capability with the same idle timeout before reporting success.

Without a coordinator, Crabbox resolves the direct SSH lease and calls the provider's existing Touch capability. This fallback requires an exact local claim for the canonical provider. Static scopes must match the configured provider scope and live resource identity exactly. Providers with a dynamic runtime scope may hydrate their recorded context, but must validate the live endpoint/daemon identity and exact resource before authorizing. The provider then compare-and-swaps the carried claim snapshot, so a disappeared or replaced claim is never recreated or overwritten. Terminal leases are rejected before touch. Providers without lease-touch support fail with provider=<name> does not support lease heartbeat.

Idle timeout

--idle-timeout <duration> optionally replaces the lease's idle window while refreshing it. The value must be positive. Omitting the flag preserves the current direct-provider timeout when it is available in lease metadata and omits the coordinator heartbeat override. Direct static and local-runtime providers persist the refreshed timestamps, expiry, and any explicit timeout replacement in the exact claim so a fresh CLI process observes the same state.

Output

Human output is one line with the lease ID, slug, provider, state, idle timeout, last-touch timestamp, and expiry. --json emits the same fields as a JSON object.

Flags

--id <lease-id-or-slug>
--provider <provider>
--idle-timeout <duration>
--json

See also

• status — read the current lease state without touching it.
• inspect — inspect full lease and provider details.
• run — run a command with automatic background heartbeats.