Skip to main content

​
crewship capacity

Show what host admission control is doing right now.
Crewship holds a crew container start — before the container is created — when the host cannot afford another one, and starts it when it can. This command is how to tell a held start from a hung one.

​
Reasons

​
What the person waiting sees

You should not need this command to find out that your own run is queued. A held start reports itself on the stream that started it:
The line repeats on an escalating schedule — roughly at 30s, 1m, 2m, 4m, 9m, 19m and 29m — so a long wait keeps saying so without becoming a line per poll. It also repeats immediately when the binding reason changes (host memory frees, but the concurrency bound is now what holds you). The same events land in the run journal as provision capacity_hold rows, carrying reason and the numbers, and on the Activity Bar as Waiting for host capacity.
The apple container provider emits no other container-preparation events — no create, no ready — but it does emit this one. The host-memory leg is inactive on macOS, but the concurrency bound and the stagger still bind there, so a start can be held on that provider too.

​
When a hold runs out

A hold is not infinite: it ends when the run’s own deadline does — 30 minutes for a chat or agent run, 45 for the scheduler. When that happens the failure names the resource that ran out rather than blaming provisioning:
The machine-readable code for this failure is capacity, distinct from resource_limit (a limit the container runtime itself refused) and from provision_failed (the image or the daemon).

​
Thresholds

All four are instance settings, read live — a change takes effect on the next held start, not the next restart.
See Sizing a crew → Host capacity for why the floor is an absolute figure rather than a percentage, and why starts are staggered.

​
Platform support

The host-memory signal comes from /proc/meminfo and /proc/pressure/memory, which exist on Linux only. On macOS — where the apple container provider runs — the host-memory gate is inactive, and this command reports host-memory gate inactive (signal unavailable on this platform) rather than presenting a gate that is quietly doing nothing. The concurrency bound and the stagger still apply. /proc/pressure/memory further needs a kernel built with CONFIG_PSI; where it is missing the pressure veto never fires, and its absence is never read as pressure.

​
Scope

Admission control answers exactly one question: should this host start one more crew container right now, or wait. It does not tune cgroups, evict, or rebalance, and it never touches a container that is already running — a running container cannot be paused to free memory (docker pause is a single write to cgroup.freeze; the cgroup keeps every page). Reusing a crew container that is already running costs the host nothing and is never held. Only a create, or the restart of a stopped container, goes through the gate.

​
API

Read-only and instance-scoped. The request requires authentication (401 when missing) but no workspace role or admin permission. The endpoint returns 200 OK with JSON; it does not accept a request body and has no mutating operation. The route is not workspace-filtered because the snapshot describes the host and all starts held by this daemon.

​
See also