Support selectable Runtime images per Environment Template

Start by reading contracts/agents-api/sandbox-deployment.md, contracts/agents-api/environment_templates.go, and services/core/internal/sandbox/deployment.go to trace how deployment images and Template requests are represented. Then inspect the runtime deployment schema and node image readiness and pinning paths. Before implementation, resolve the open questions about image scope, pools, preloading, and retirement; done means a registered image can be selected and frozen for a Session, with unsupported or unavailable images handled distinctly.

Problem

An installation runs every Sandbox on exactly one Runtime image. The image is pinned by digest in the single deployment specification, so all Projects share it. Administrators cannot give a Project a different toolchain, which blocks heterogeneous workloads that need different preinstalled system software.

A single installation typically serves several kinds of work whose system dependencies barely overlap:

• code review needs SCM and review CLIs, such as git plus a hosted-platform CLI;
• web prototyping needs pnpm and a browser toolchain;
• design and rendering work needs its own native libraries and large toolchains.

Several of these are individually large. Forcing them into one image makes every Sandbox pay the full size and build surface of every unrelated toolchain, which slows preparation and pushes the image past practical limits. Because packages.system is rejected, a Project cannot add a system dependency to the image at Session time, so the only workarounds are:

• bake every toolchain into one shared image, growing it for all Projects; or
• run a separate installation per toolchain, duplicating Core, its database, its keys and its nodes.

Where the single-image assumption lives

• Contract: contracts/agents-api/sandbox-deployment.md states the deployment holds "one active selection per installation" and that provider is "exactly one of docker, microsandbox, e2b". docs/getting-started/nodes.md says "Sandbox settings apply to the whole installation; nodes follow them."
• Schema: runtime_deployment is a singleton table (singleton boolean PRIMARY KEY DEFAULT true CHECK (singleton)). The image identity lives in the immutable specification JSON, and runtime_deployment_generations retains one specification per generation.
• Image identity: services/core/internal/sandbox/deployment.go defines RuntimeRelease as one source_commit, image_id, image_manifest_digest, microsandbox_ref, runtime_sha256 and firmware_sha256; validation requires "one immutable distribution" per release.
• Provider: services/core/internal/sandbox/providers/microsandbox.go carries a single Image string, and services/core/internal/sandbox/microsandbox/identity.go parses exactly one name@sha256:<digest>.
• Templates: contracts/agents-api/environment_templates.go exposes network, env, files, packages, plugins, skills and setup_commands, but no way to select a Runtime image.
• Node distribution: nodes load and pin the image named by the current deployment generation; a node's serving pin is durable across offline periods.

Proposal

Let a Runtime image be a first-class, named resource, and let an Environment Template select one.

• Introduce an installation-scoped image registry: each entry is a complete RuntimeRelease (the six hashes already defined) plus a name, an optional description and the provider kinds it supports. Entries are immutable once referenced.
• runtime_deployment keeps the provider, resources and the default image, and gains a set of selectable images. The default image remains the fallback when a Template does not select one.
• EnvironmentTemplateRequest gains an optional runtime_image_id. When omitted or null, the Session uses the deployment default, so existing Templates keep working unchanged.
• At Session admission, Core resolves the Template's image and freezes its full release identity onto the placement and allocation, exactly as deployment_generation is frozen today. Existing generation immutability rules still apply; an image reference is part of the frozen specification, never re-resolved later.
• Node lifecycle: a node advertises and pins the set of images it has prepared. Core places a Session only on a node ready for the selected image. Missing images show a distinct readiness state so the administrator can see what still needs to download.
• API and Web: add image CRUD under /core/v1/sandbox/ and image selection to the Environment Template editor. Update the OpenAPI, sandbox-deployment.md and its zh translation, and the @oac/agents-client validators.

Constraints

• Image selection happens at Session creation from the frozen Template. A running Session, allocation or suspended Environment never changes image; restores keep their original image.
• An Environment Template may only select an image the installation has registered and the target provider supports. Unknown or unsupported images fail validation with a clear param error.
• Image absence must not silently fall back to the default image. A missing image is a placement failure with a distinct reason, never a substitution.
• The image registry is deployment-wide configuration, not a Project-owned resource, so a Project cannot introduce an image for other Projects.
• No provider-name branches: image readiness and preparation go through the registered adapter declarations.

Alternatives considered

• Bake every tool into one shared image. Works today, but every Project pays the size and the build surface of every other Project, and native toolchains that conflict at the system level cannot coexist.
• Use setup_commands to download tools at every Session start. It repeats per Session, has no offline guarantee, and cannot satisfy tools that a Template alone is expected to guarantee.
• Run one installation per toolchain. This is supported and needs no code change, but duplicates Core, its database, its keys, its nodes and its upgrades per toolchain.

Open questions

• Should an image be selectable per Environment Template, per Project, per Harness, or several of these? This issue proposes Template-level selection as the smallest change that unblocks the use case, with the deployment default preserving current behavior.
• How does this interact with Support multiple ordered sandbox pools per installation (#397)? Pools and images are orthogonal: a pool selects where a Sandbox runs, an image selects what runs in it. Should image readiness be a pool-level or node-level property?
• Should nodes preload all registered images eagerly, or on first demand for a selected image? Eager loading guarantees placement but multiplies disk use per node.
• What bounds the number of registered images, and how are retired images garbage-collected once no retained generation references them?