Capacity

Predictive burst remains undesigned. capacity show, capacity cost, capacity provider list, capacity pool CRUD, and the capacity profile verb set below are real and reflect live data. Placement runs the six-stage composition law: when a dispatch has no permitted-and-viable candidate, the platform returns a loud, typed failure naming every pool it considered and the stage and rule that excluded each one - never a silent queue, never a silent downgrade, and no longer the flat "dispatch abandoned" message this page used to describe. A profile's burst posture (off | manual | auto_when_entitled, default off) controls whether it may reach capacity it does not name once an observed failure occurs - see Capacity profiles - burst posture. What is not built: reaching for more capacity before a dispatch has actually failed. Predictive or capacity-triggered bursting would need usage-meter telemetry (token/credit budgets) the platform does not currently collect.

rensei capacity is the org-level view of execution infrastructure - every host and sandbox running right now across your organization, which capacity profile a project is granted, what providers and pools exist, their current utilization, and how much agent compute has cost you over a given window. Use it to see every registered host in your org, manage capacity profiles, provision new pools, and track spend before reviewing the billing dashboard.

For capacity that is scoped to the local machine (the daemon running on your laptop or a registered build host), use rensei host capacity. The rensei capacity commands shown here operate org-wide.

Deprecated and removed aliases

As of v0.9.0 the CLI has exactly two top-level nouns - host (this machine) and capacity (the org's execution capacity):

rensei fleet was deprecated in v0.9.0 and removed in v0.10.0. It no longer resolves: the binary answers unknown command. Its five leaves mapped onto capacity unchanged - same platform endpoint, same wire row:

Removed	Current
`rensei fleet list`	`rensei capacity show --kind persistent-host`
`rensei fleet show <id>`	`rensei capacity show <id>`
`rensei fleet route show`	`rensei capacity route show` (now itself deprecated - see below)
`rensei fleet route set`	`rensei capacity route set` (now itself deprecated - see below)
`rensei fleet route test`	`rensei capacity route test` (now itself deprecated - see below)

See Fleet (removed).

rensei execution * no longer exists. It was a hidden alias for rensei capacity * from the 2026-05-06 rename; the alias window closed after 84 releases and execution was deleted outright in v0.9.0, not just deprecated further. Update any scripts to call rensei capacity directly.

Commands

`capacity show`

Print a unified live view of all execution capacity available to the org - persistent local hosts and on-demand cloud sandboxes combined. This is also the single-instance detail view (formerly fleet show) and the persistent-host-only list (formerly fleet list), selected with an optional positional id or --kind.

rensei capacity show [<instance-id>] [--kind persistent-host|on-demand-sandbox] [--json]

Argument / Flag	Description
`<instance-id>`	Optional. Show detail for one live instance instead of the full list. Accepts the bare machine id (`mac-studio`) or the fully-qualified live-instance id (`host:mac-studio`) - both resolve. Mutually exclusive with `--kind`.
`--kind`	Filter the list view to `persistent-host` (registered machines only - the view formerly at `fleet list`) or `on-demand-sandbox` (ephemeral cloud workers only). Omit for everything.
`--json`	Emit the raw wire envelope, unwrapped, for scripting (`jq`, etc.)

# Everything: pool summary + every live instance
rensei capacity show

# Just the registered machines (the fleet list replacement)
rensei capacity show --kind persistent-host

# Just the ephemeral cloud sandboxes
rensei capacity show --kind on-demand-sandbox

# Detail for one instance (the fleet show replacement) - on-demand sandboxes
# are addressable here too, which `fleet show` never supported
rensei capacity show mac-studio
rensei capacity show host:mac-studio --json

Filters are flags and ids are positionals - a future filter cannot claim the positional slot, so --kind and <instance-id> are always mutually exclusive.

Example output:

Pools (4):
  POOL             PROVIDER  MODE        INSTANCES  SESSIONS  COST (24H)
  Local Main       local     hybrid      3          8/16      -
  GPU Workloads    local     persistent  1          0/4       -
  E2B Sandboxes    e2b       on_demand   0          0/∞       $14.28
  Modal GPU        modal     on_demand   0          0/∞       $6.05

Live instances (4):
  ID                HOSTNAME       PROVIDER  MODE        STATUS  SESSIONS  REGION  LAST SEEN
  host:build-01     build-01.corp  local     persistent  ready   2/4       -       2s ago
  host:dev-mbp-mark dev-mbp-mark   local     hybrid      ready   0/2       -       5s ago
  host:ci-runner-001 ci-runner-001 local     persistent  draining 0/8      -       12s ago
  sbx:e2b-8f3a2     -              e2b       on_demand   ready   1/1       us-east-1  9s ago

(The real CLI renders the empty-value placeholder as a Unicode em dash; this page uses a plain hyphen so the example output does not trip this site's own voice lint.)

Persistent hosts sort first (by hostname), then on-demand sandboxes (newest spawn first). The REGION column makes capacity show --kind persistent-host a strict superset of the fleet list table it replaces.

`capacity profile`

The current command family for reading and editing an org's capacity profiles - the org-authored, project-granted object documented in full on Capacity profiles. It replaces capacity route, deprecated below.

rensei capacity profile <list|show|set|grant|test> ...

`capacity profile list`

Every capacity profile authored in your org.

rensei capacity profile list [--json]

Example output:

Capacity Profiles (2):
  NAME             ID         POOLS  POLICY    DEFAULT
  default          prof_...   2      declared  yes
  gpu-inference    prof_...   1      cost_aware

`capacity profile show`

One profile's ordered pool list, ordering policy, and postures.

rensei capacity profile show <profile>

<profile> may be the exact profile id or its name (case-insensitive). A name that matches more than one profile is refused with the candidates listed, rather than guessing.

Example output:

Capacity Profile: default
  ID:          prof_...
  Org default: true
  Revision:    3
  Policy:      declared
  Reservation: none
  Disconnect:  lost-after=300000ms replace=true reconcile=best_score
  Auto-scale:  off

Ordered pools (2):
  1. pool-local-main
  2. pool-cloud-e2b

`capacity profile set`

Edit a project's granted capacity profile - specifically, the ordered pool preferences and ordering policy of whichever profile the project currently has selected. If that profile is shared with other projects, the platform forks a project-exclusive copy first, so this edit never mutates another project's routing.

rensei capacity profile set [<project>] \
  [--preferred-pool <pool-id>] [--fallback-pool <pool-id>] \
  [--clear-preferred] [--clear-fallback] \
  [--policy declared|ordered_fallback|least_loaded|round_robin|affinity|cost_aware]

Flag	Description
`--preferred-pool <pool-id>`	Preferred execution pool id
`--fallback-pool <pool-id>`	Fallback execution pool id
`--clear-preferred`	Explicitly clear the preferred pool - mutually exclusive with `--preferred-pool`
`--clear-fallback`	Explicitly clear the fallback pool - mutually exclusive with `--fallback-pool`
`--policy <value>`	One of the six ordering policies; default: unchanged

The write is patch-semantic: a flag you do not pass is left untouched. --clear-preferred / --clear-fallback send an explicit clear - something the retired capacity route set could never do, since omitting a flag there always meant "leave it alone," with no way to empty a slot.

rensei capacity profile set my-fintech-app \
  --preferred-pool pool-local-main \
  --fallback-pool pool-cloud-e2b

rensei capacity profile set my-fintech-app --policy cost_aware

`capacity profile grant`

Grant a named capacity profile to a project - org admin or owner only. Per the org-authors/project-consumes model, only an org admin may grant; a project can never grant itself a profile.

rensei capacity profile grant [<project>] --profile <profile-id-or-name> [--primary=true|false]

At most one live primary grant exists per project; granting a new primary revokes the project's previous one in the same transaction. Pass --primary=false to grant a non-selected copy without switching the project's active routing.

rensei capacity profile grant my-fintech-app --profile gpu-inference

`capacity profile test`

Probe the placement resolver for a project the same way a real dispatch would, and render the typed decision it produced: every candidate pool considered, each excluded candidate with the stage and rule that excluded it, the ordered surviving set (which is the fallback chain), and the chosen target.

rensei capacity profile test [<project>] [--json]

rensei capacity profile test my-fintech-app

Example output:

Selected worker: wkr_...
Selected host:   host_...
Selected pool:   pool-local-main
Reason:          highest-ranked eligible pool

Outcome:         selected
Ordering policy: declared

Candidates considered (2):
  pool-local-main (local)
  pool-cloud-e2b (e2b)

Exclusions (0):
  (none)

Ordered surviving set: [pool-local-main pool-cloud-e2b]

Unlike the retired capacity route test, a decision with no viable candidate still prints the full breakdown - the exclusions are the answer to "why" - but the command still exits non-zero so scripts keep detecting failure the same way. See Decision records & explain for the equivalent read against a past dispatch rather than a live probe.

Removed: `capacity route`

rensei capacity route {show,set,test} were deprecated in favor of rensei capacity profile and have been removed as of v0.11.30. Migrate scripts to the capacity profile commands above - route show/route set mapped onto profile show/profile set, and route test mapped onto profile test. capacity profile additionally exposes profile list, which route never had: route only ever read a single project's route, never the org's named profile objects.

`capacity route show` (removed)

Removed - read a project's granted profile via capacity profile list/capacity profile show instead.

rensei capacity route show [<project-slug>]

Example output:

Execution Route:
  Project: my-fintech-app
  Policy:  ordered_fallback
  Allowed:   [pool-local-main pool-cloud-e2b]
  Preferred: [pool-local-main]
  Fallback:  [pool-cloud-e2b]
  Forbidden: []

This reads through the same underlying capacity-profile tables as capacity profile show; the Allowed / Preferred / Fallback / Forbidden shape above is this command's own legacy rendering of the project's granted profile, not a separate object.

`capacity route set` (removed)

Removed - use rensei capacity profile set instead. Same flags, same underlying write path.

rensei capacity route set [<project-slug>] \
  --preferred-pool <pool-id> \
  [--fallback-pool <pool-id>]

`capacity route test` (removed)

Removed - use rensei capacity profile test instead. Unlike profile test, this command's unsatisfiable case did not print the full exclusion breakdown.

rensei capacity route test [<project-slug>]

`host migrate`

Moves a registered host to a different execution pool. Registered as rensei host migrate, not rensei capacity host migrate - it lives under the host noun because it names this machine's pool assignment, the same reason rensei host capacity is a separate surface from the org-wide commands on this page. Admin or owner only.

rensei host migrate <host-id|machine-id|hostname> --to-pool <pool-id>

The argument may be the platform's exact host id, or the machine id / hostname printed by rensei capacity show --kind persistent-host - this command resolves it against the org's host inventory first, the same way rensei host deregister / rensei host restore do. The host's current pool (the migration source) is read from that same inventory lookup - there is no --from-pool flag, because the platform already knows it. The target pool must exist, be live, and not be disabled.

rensei host migrate mac-studio --to-pool pool-cloud-e2b

The daemon does not need to be told: it keeps heartbeating under its existing worker id, and its next heartbeat's pool read reflects the move.

Placement and the composition law

Placement runs the six-stage composition law against the project's granted capacity profile: permission and viability filter the profile's ordered pool list down to what is permitted and able to run the session; the profile's ordering policy ranks the survivors; the head of the ranked list is bound. Falling to the next pool in that ranked list on an observed acquisition failure is the platform's one fallback rule - there is no separate, hand-authored fallback list to consult.

For the profile object itself (ordered pools, all six ordering policies, burst posture, disconnect reconciliation), see Capacity profiles. For reading what a specific past dispatch actually decided and why, see Decision records & explain.

`capacity cost`

Show aggregated compute cost for the org over a sliding time window.

rensei capacity cost [--window 24h|7d|30d] [--json]

Flag	Default	Description
`--window`	`24h`	Time window: `24h`, `7d`, or `30d`
`--json`	-	Emit a JSON cost breakdown

rensei capacity cost --window 24h
rensei capacity cost --window 30d --json

Example output:

Compute cost - last 7 days
===========================

By pool:
  pool-local-main        $0.00   (self-hosted, no platform compute charge)
  pool-cloud-e2b         $14.28  (47 sessions × avg 18 min)
  pool-cloud-modal       $6.05   (8 GPU sessions × avg 22 min)

By project:
  my-fintech-app         $12.41
  internal-tools         $7.92

Total:                   $20.33

Self-hosted pools (local provider) accrue no Rensei compute charges. Cost tracking for those pools reflects the sessions executed but shows $0.00. Use the Factory cost breakdown dashboard for a full human-vs-agent cost view.

`capacity provider list`

List all sandbox and execution providers registered in the org.

rensei capacity provider list

Providers are the underlying substrate that pools are built on. Each provider has a family (sandbox, workarea, runtime, etc.) and a set of capability flags. See Sandbox providers - add a provider for the full capability matrix.

`capacity pool list`

List all execution pools in the org.

rensei capacity pool list [--json]

Flag	Description
`--json`	Emit pool array as JSON

rensei capacity pool list
rensei capacity pool list --json | jq '[.[] | select(.mode == "on_demand")]'

Example output:

ID                  NAME              PROVIDER   MODE         HOSTS  SESSIONS
pool-local-main     Local Main        local      hybrid       3      8/16
pool-local-gpu      GPU Workloads     local      persistent   1      0/4
pool-cloud-e2b      E2B Sandboxes     e2b        on_demand - 0/∞
pool-cloud-modal    Modal GPU         modal      on_demand - 0/∞

`capacity pool create`

Create a new execution pool.

rensei capacity pool create \
  --provider <provider-id> \
  --name "<display-name>" \
  --mode persistent|on_demand|hybrid

Flag	Required	Description
`--provider`	Yes	Provider ID from `capacity provider list`
`--name`	Yes	Human-readable display name for the pool
`--mode`	Yes	`persistent`, `on_demand`, or `hybrid` - see Pool modes. Note: mode never changes `--provider`; a `local`-provider pool in any mode is still local-daemon-only capacity.

# Create a pool that serves both persistent local workers and on-demand
# provisioning from the SAME provider (still just `local` - hybrid does not
# add a second, cloud provider to this pool)
rensei capacity pool create \
  --provider local \
  --name "Backend Local" \
  --mode hybrid

# Create an on-demand cloud pool for GPU inference tasks
rensei capacity pool create \
  --provider modal \
  --name "GPU Inference" \
  --mode on_demand

The created pool's ID is printed on success. Add it to a capacity profile's ordered pool list with rensei capacity profile set to start routing project work to it.

`capacity pool show`

Show configuration and live status for a single pool.

rensei capacity pool show <pool-id>

rensei capacity pool show pool-local-main

Includes current host membership, per-host session counts, pool mode, and the runtime_provides capability list. See Capacity pools for how runtime_provides affects substrate resolution.

`capacity pool update`

Patch an execution pool. <pool> may be an exact pool id (expool_…) or an unambiguous pool name scoped to the selected organization - unknown and ambiguous names are refused before any PATCH, and an exact id bypasses the name-resolution list.

rensei capacity pool update <pool> \
  [--name <name>] [--mode persistent|on_demand|hybrid|drained] [--status active|paused|draining|disabled] \
  [--substrate-class local|ephemeral] [--credential <org-credential-id>] \
  [--cost-weight <n>] [--priority <n>] [--receipt-forwarding on|off] [--json] \
  [--allowed-project-id <id>] [--unrestricted] [--quarantined]

Flag	Description
`--name <name>`	New display name.
`--mode <mode>`	`persistent`, `on_demand`, `hybrid`, or `drained`. See Pool modes.
`--status <status>`	`active`, `paused`, `draining`, or `disabled`.
`--substrate-class <class>`	`local` or `ephemeral`.
`--credential <id>`	Org credential id to bind; empty string unbinds.
`--cost-weight <n>`	Relative cost weight for `cost_aware` routing (default 100).
`--priority <n>`	Selection priority (default 100).
`--receipt-forwarding on\|off`	Forward terminal execution receipts for this pool (see Receipt forwarding). Off unless explicitly enabled.
`--json`	Emit a secret-free update receipt as JSON (`poolId`, `poolName`, `providerId`, `requestedReceiptForwarding`, `effectiveReceiptForwarding`).
`--allowed-project-id <id>`	Project id allowed to use this pool (repeatable).
`--unrestricted`	Set `allowedProjectIds` to `null` (all projects may use the pool).
`--quarantined`	Set `allowedProjectIds` to `[]` (no project may use the pool).

Only flags you pass are sent; omitted keys preserve the stored value. --allowed-project-id / --unrestricted / --quarantined are mutually exclusive.

# Rename a pool
rensei capacity pool update pool-local-main --name "Primary Local Fleet"

# Switch a local pool to hybrid (it can now also be picked for on-demand
# provisioning - still `local` capacity only, not a cloud provider)
rensei capacity pool update pool-local-main --mode hybrid

# Enable receipt forwarding for a pool (v0.14.21+)
rensei capacity pool update expool_1 --receipt-forwarding on
rensei capacity pool update expool_1 --receipt-forwarding off --json | jq .effectiveReceiptForwarding

Changing pool mode from persistent to on_demand takes effect immediately for new sessions. In-flight sessions on local hosts are unaffected. on_demand mode does not change a pool's provider: an on_demand pool with providerId: local still requires a live local daemon; only a pool whose provider is an actual cloud/sandbox provider (e2b, daytona, modal, vercel, docker, kubernetes) can spawn cloud sandboxes.

--receipt-forwarding controls whether terminal execution receipts from this pool are forwarded to the daemon and whether adaptation receipts are persisted under the state home (adaptation-receipts). The CLI validates on/off before authentication, refuses unknown/ambiguous pool names, and reports the effective state read back from the platform in both human and --json output.

`capacity pool delete`

Delete an execution pool. The pool must have zero active sessions.

rensei capacity pool delete <pool-id>

rensei capacity pool delete pool-cloud-e2b

A profile's ordered pool list is foreign-key-validated on write, so a pool referenced by a profile cannot be deleted out from under it while the reference stands - remove the pool from every profile that names it first with rensei capacity profile set.

Pool modes

A pool has exactly one providerId (local, docker, kubernetes, e2b, daytona, modal, vercel). Mode does not add a second provider to a pool - it only toggles which selection paths (servesPersistent / servesOnDemand) the pool is eligible for:

Mode	Description	Best for
`persistent`	`servesPersistent` only. Eligible for the persistent-worker selector (registered local/docker/kubernetes hosts).	Security-sensitive workloads, BYOK model auth, BFSI compliance
`on_demand`	`servesOnDemand` only. Eligible for on-demand provisioning against this pool's one provider. For a cloud provider (`e2b`, `modal`, ...) this spawns a sandbox; for `providerId: local` it still requires a live local daemon - there is no cloud fallback.	Elastic cloud workloads (with a cloud provider pool), GPU inference
`hybrid`	Both flags set. Eligible for both selectors, but still against the pool's single provider - it does not cause a `local` pool to spill work to a different, cloud-provider pool when local capacity is exhausted.	A local pool you also want reachable by the on-demand selector

To get local-first-then-cloud behavior, add both a local pool and a cloud-provider pool to a capacity profile's ordered pool list, local pool first - understanding that, per Placement and the composition law above, falling to the cloud pool happens on an observed acquisition failure, not pre-emptively.

For the full relationship between authMode and pool selection constraints (some auth modes require local pools), see LLM auth modes.

Placement, Selection & Routing Vocabulary - the six-stage law, and what "routing" means on other pages
Capacity profiles - the profile object: ordered pools, all six ordering policies, burst posture, disconnect reconciliation, and the grant model
Decision records & explain - reading what a past dispatch actually decided
Host daemon - install this machine as a host, plus host deregister / host restore
Host capacity - per-machine envelope - tune maxConcurrentSessions and poolMaxDiskGb on the local host
Fleet (removed) - the retired alias tree this page absorbed, removed in v0.10.0
Sandbox providers - provider capability matrix
Factory cost breakdown - human-vs-agent cost analytics

On this page