Host capacity
cua.env.v1 HostNodeStatus and HostMeasured: what a host reports for placement (capacity, load, measured memory).
What a host reports to whoever places Spaces and jobs on it: HostNodeStatus (kinds, runtimes, CPU and memory, jobs) and, in HostNodeStatus.measured, what it measures rather than reserves: available memory, memory pressure, and how many more VMs fit when VMs share snapshot memory.
Source: libs/cua/proto/cua/env/v1/capacity.proto.
Types in cua/env/v1/capacity.proto#
HostMeasured#
What a host measures rather than reserves, for placement
(HostNodeStatus.measured). Reservations count what Spaces may use; these
count what they use, so VMs restored from one snapshot, whose unwritten
memory is shared, fit many times more than their reservations say.
| Field | # | Type | Description |
|---|---|---|---|
memory_available_mb | 1 | uint64 | Memory the OS says new work can use now, in MiB, whatever reserves it (Linux MemAvailable; macOS kern.memorystatus_level of physical memory). 0: the OS does not say. |
memory_pressure | 2 | uint32 | Memory pressure: 0 normal, 1 warn (the OS compresses or swaps), 2 critical (it is about to kill processes). A scheduler sends nothing to a host at 2. |
vcpu_overcommit | 3 | float | The host's VM CPU overcommit (CUA_VM_VCPU_OVERCOMMIT): a vm Space's vCPU reserves 1/this of a host CPU (millicpus_*), because VMs of rollouts and agents mostly wait. 0 or 1: none. |
vm_memory_known | 4 | bool | vm_memory_free_mb and vm_typical_mb are measured (the host runs QEMU VMs and its OS reports memory). |
vm_memory_free_mb | 5 | uint64 | VM memory this host takes now, in MiB: what its VM memory cap (CUA_VM_MAX_RSS_FRACTION of physical memory), its available-memory floor and its hypervisor's VM limit leave, counting what VMs restored from one snapshot share once. For a vm Space a scheduler checks this, not the reservations in HostNodeStatus.memory_free_mb. |
vm_typical_mb | 6 | uint64 | What a running VM here uses (the median, MiB): what one more is expected to need. 0: no VM runs. |
HostNodeStatus#
A host as one of your machines that run work: what a scheduler reads to place Spaces
and jobs here (GetHostSpacesResponse.node, and every
HostJobsService answer, which doubles as the node's heartbeat).
| Field | # | Type | Description |
|---|---|---|---|
boot_id | 1 | string | Random per start of the host's cua daemon: a new value means the daemon restarted (its running jobs ended with error). |
epoch | 2 | uint64 | Increases by one on every start of the host's job runner (kept on disk), so a scheduler can order restarts. |
host_time_ms | 3 | int64 | The host's wall clock when it answered (Unix milliseconds), for clock-skew detection. Leases never depend on it. |
millicpus_total | 4 | uint32 | CPU this host offers to Spaces and jobs, in thousandths of a CPU. |
millicpus_free | 5 | uint32 | Of that, not reserved by running jobs and provided Spaces. |
memory_total_mb | 6 | uint64 | Memory this host offers to Spaces and jobs, in MiB. |
memory_free_mb | 7 | uint64 | Of that, not reserved. |
running | 8 | map of string to uint32 | Running Spaces by kind (container, vm, microvm): the ones this host provides and the ones its jobs run in. |
kinds | 9 | repeated string | Kinds this host can create (container, vm, microvm), and machine when it is dedicated (dedicated). |
runtimes | 10 | repeated string | Runtimes this host offers (gvisor, runc, qemu, lume, firecracker, ...). |
jobs_running | 11 | uint32 | Jobs running now. |
jobs_max | 12 | uint32 | Most jobs this host runs at once (0: bounded by CPU and memory only). |
ledger_id | 13 | string | Identifies this host's job ledger: a new value means the ledger was lost (a wiped disk) and jobs it acknowledged are unknown to it. |
ledger_seq | 14 | uint64 | The newest job ledger sequence number (see ListHostJobs). |
draining | 15 | bool | The host takes no new jobs. |
problem | 16 | string | Why this host cannot take jobs now, for people (a full disk, Spaces off). Empty when it can. |
arch | 17 | string | CPU architecture (x86_64, aarch64). |
warm | 18 | map of string to uint32 | Ready warm-pool members by shape (warm_key: <image>|<kind>|<runtime>|<cpus>|<memory_mb>, an empty part being auto or the default size): a Space of that shape starts here without a cold start, so placement (on="auto") prefers this host. |
accelerators | 19 | repeated string | Accelerators this host offers to jobs, one per GPU (Apple silicon: one): <vendor>:<model>:<detail>..., e.g. apple:M2 Max:38-core GPU:96 GB (unified memory) or nvidia:L4:23 GB. Empty: none. |
addresses | 20 | repeated string | This host's IPv4 addresses other machines may reach its jobs on, as ip/prefix with the interface's own netmask (172.31.20.9/20): LAN first, then tailnet (100.64.0.0/10), then public. Loopback, container and VM bridges are left out. |
native_jobs | 21 | bool | Deprecated. Deprecated, never set: native jobs (kind = "process", a command run on the machine itself, outside any Space) are gone; every job runs in a Space. Kept so older readers see false. |
usd_per_hour | 22 | double | What an hour of this host costs, in US dollars (CUA_HOST_USD_PER_HOUR: a cloud instance's price; 0 for machines you own), for cost estimates. |
self_fence_after_ms | 23 | uint32 | A host cut off from its scheduler stops its own gang members (they end canceled, their error starting fenced:): they are gone at most this long after their scheduler's last ListHostJobs call (the host's wait, CUA_SELF_FENCE_AFTER_SECS, default 60 s, plus the time stopping them takes). A scheduler places their gang again only after that, so a member never runs next to the attempt that replaced it. 0: the host does not fence itself (an older host). |
dedicated | 24 | bool | The machine exists only for Cua work (a cloud instance cua cloud add aws made, set up with cua host setup --dedicated): it offers its own Space (kind = "machine", in kinds), where job members run with its GPU and drivers as they are. A user's own computer is never dedicated. |
measured | 30 | HostMeasured | Measured, not reserved, capacity. |
snapshots | 40 | map of string to string | Checkpoints held here: name to manifest digest. |
snapshot_abis | 41 | repeated string | Checkpoint ABIs restored here (qemu/hvf/aarch64). |
job_services | 25 | bool | This host's job runner acts on HostJobSpec.services (field 16): it starts the named host services for each member, or refuses the job. A host that predates the field (or never sets this) drops services silently, so a scheduler places a job that asks for services only on hosts that report true, and fails it with a clear error when none do. |