Templates and warm pools

The controller owns desired state#

Register a template in the controller. It synchronizes the registered revision to configured nodes and records each node's installation outcome. Newly configured nodes join reconciliation after the controller reloads its host configuration.

Templates are separate from the Engine Box installation. A manifest defines its supported recipe, source image, tools and minimum/recommended resources. Existing private workspaces are not rebuilt when the template changes.

Use a supported manifest#

Start with native-dev.json or native-desktop.json. The current recipe is native-clients-v1 on Ubuntu 24.04. It can prepare official clients and browser/desktop tools.

Register through the Templates dashboard, MCP template_register, or POST /v1/templates with a manifest object or an HTTPS url. Use template_sync to retry fleet synchronization. Inspect per-node status before allocating.

Manifests reject unknown fields and arbitrary installation scripts. Provider credentials and repository secrets never belong in a template. Increment the manifest revision to publish a changed recipe. A project's future dev start command belongs to the planned environment service, not this manifest.

Choose resources at allocation#

Minimum and Recommended come from the registered template. Custom allocations specify CPU, memory and disk, all at or above its minimum. The controller checks real host capacity again when the job executes.

For POST /v1/hosts/{host_id}/allocations, a typical body is:

{
  "name": "ebox-work",
  "template": "native-dev",
  "size": "recommended"
}

Only a successfully installed revision is allocatable on that host. A queued request does not reserve capacity. Keep host headroom for CI and ordinary processes outside Incus.

Fresh means never assigned#

A warm pool prepares and pauses credential-free VMs in advance. Allocation claims one permanently, delegates authorized access and verifies readiness. If no compatible reserve exists, the controller can create a cold clone.

Assigned VMs never return to the fresh pool. Use the actual instance name returned by allocation for later lifecycle calls; a reserve can have a different name from the requested workspace label.

Paused reserves retain memory allocations. Size the pool against the resources you can keep committed. See warm-pool configuration and template synchronization.