Offer templates to every user
Preview. Deployment templates, the template store and its policy are implemented but not yet declared Stable; interfaces and limits may change. Known limits: Limits operators must know.
A template every user of the sandbox service can create sandboxes from comes one of two ways: the
deployment declares it in its own settings, or it is a template in the template store with
deployment visibility. This page says which to choose, and the short version of each.
The runbook's §5 and
The template host agent are the full procedures; what users do
is Make a template from a container image.
Which way​
| Your deployment | Use |
|---|---|
No template store (SBX_TEMPLATE_STORE unset or 0) | declared templates: the only way |
A template store (SBX_TEMPLATE_STORE=1) with host agents | deployment-visible templates in the store |
| A template store, before the control plane's first start | either: the declared list is imported into the store once, at that start |
The declared list is read into the store once. With SBX_TEMPLATE_STORE=1,
SBX_TEMPLATES_FILE is imported into the empty store at the control plane's first start, and
ignored after that: a later change to it only logs a warning that the list differs from the
catalog. On a deployment with a store, add new templates
through the store.
Declared templates​
A declared template is an entry in SBX_TEMPLATES_FILE, served by one worker listed in
SBX_WORKERS, both in the env file setup.sh reads (the install reference). It has
no owner, it is visible to everyone, and it needs no activation: its worker is the deployment's to
run, always on. The short version, from a container image:
- On the KVM host,
deploy/sbx/template-onboarding/template-build.sh SPEC --kernel PATHbuilds the snapshot, checks it in a microVM, and writes a template record. - On your machine,
deploy/sbx/template-onboarding/template-register.sh --env-file FILE RECORDadds the record's worker toSBX_WORKERSand its entry to the templates file. - Re-run
setup.sh: it mints the worker's relay token and writes its bundle. It rolls the control plane, not the relay. - On the KVM host,
install-host.sh BUNDLE --snapshot <snapshot>installs the worker, which attaches to the relay (--budget-mb Nfor a guest larger than 256 MiB,--no-egressfor a template with no network). - Check it with
deploy/sbx/templates-check.sh(the runbook's §14).
An update is a new worker for the new snapshot; the old one stays until its sandboxes end. Steps, updates and removal: the runbook's §5, and the onboarding guide's §4 for a worked example.
Deployment-visible templates in the store​
On a deployment with the template store and host agents, a template created through
POST /v1/templates (mocactl sbx templates create) is visible to every user unless it was created
private: deployment is the default visibility. So a template for everyone is created like
any other, by you or by a user, and the user page
is the procedure. A host agent builds and probes it, and the control plane registers it by policy.
You still install each build's worker once. The host agent builds templates, and starts and
stops installed workers, but installs none: until a worker is installed, an activation on that host
is reported refused (worker not installed) and never becomes active. For a
registered build: add its worker id (sbx_<id with - as _>_<first 12 hex of the image digest>) to
SBX_WORKERS, re-run setup.sh for its relay token, and run install-host.sh with that bundle
and --snapshot <snapshot> on the host that built it
(The template host agent).
A host-built template's worker runs only under an activation lease. Anyone who can see the template
takes or renews one with mocactl sbx templates activate ID, or by creating a sandbox on it, which
takes one and answers 409 template_not_active with Retry-After. A lease lasts 60 to 86400 s and
is renewed by activating again, without limit; it counts against the activating user's active
quota. There is no setting that keeps a host-built template always running. To keep a released worker
warm for a while, set the host's idle grace, SBX_IDLE_GRACE_S in host-agent.env (default 0,
off); see the runbook's idle grace.
What an admin controls​
The stored policy (GET /v1/policy, mocactl sbx policy) gates every create. An admin changes it
with PUT /v1/policy, the whole policy as read plus the change, sent with ?expect= the digest it
was read with (Writing the policy). A write
that widens the policy is refused 403 forbidden unless the admin is named in
SBX_ADMIN_SUBJECTS.
- Profiles. The default policy has
base(no gate record; up to 16384 MiB and 8 vCPUs),benchmark, and the self-attestedgeneral-selfandbenchmark-self. The policy is stored at its first read, so a newer image's default profiles reach a running deployment only through aPUT /v1/policy. - Allowed registries. The default allows only
<default>, the KVM host's own registry (SBX_REGISTRY). Add the registries users may bring images from toallowedRegistries(Docker Hub isdocker.io), and narrow one to named repositories withallowedRepositories. - Quotas. The default is 100
templates, 10buildsQueued, 8activeand 200ownedper user. Set one user's withmocactl sbx templates quota TARGET …(the Template API's quotas). - Trusted gate records. A template built on
general-selforbenchmark-selfwith its owner's own gate record is self-attested: private, anddeploymentvisibility is refused409 self_attested. To let it be shared, add the record's sha256 (sha256:<64 hex>of its exact bytes) totrustedGateRecords: its builds then readattestation: deployment, and the owner can make the templatedeployment-visible. Removing the sha256 makes those templates private again at the next read; thePUT /v1/policyanswer lists them asnarrowed. - Withdrawing a template from everyone. The owner or an admin can make it private
(
mocactl sbx templates edit ID --visibility private) or retire it (mocactl sbx templates retire ID). An admin can also reject a registered build after the fact,POST /v1/templates/{id}/builds/{build}/rejectwith{reason}; it has nomocactlcommand and cannot be undone. A retire or reject is refused409 build_in_usewhile a sandbox runs on the build or a session is pinned to it.
The trust rules in full (one subject per self-attested record, X12.self, X1.self.egress) are in
Trusting a gate record.
How users see and use it​
mocactl sbx templateslists the templates a user can see: declared ones, deployment-visible ones, and their own private ones, each with its readiness and tags.mocactl sbx create --template ID(orsbx up --template ID) uses the build the template'sdefaulttag names. A template's first registered build takesdefault, and later builds do not move it until the owner does (mocactl sbx templates tag ID default --build BUILD).ID:TAGandID@BUILDname another build. Without--template,mocactlasks for the template whose id isdefault.- On a host-built template that is not active, the first create takes a lease and waits for the worker (Templates, builds and activation).