Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

3.3 KB
Raw Blame

title: Publish Templates to an OCI Registry description: Build Golden Image templates in an OCI registry and create Fast Sandbox instances from immutable artifacts.

Publish templates to an OCI registry

osb template create can publish Golden Image artifacts to an OCI registry. Set --publish to a repository-only address such as oci://registry.example.com/sandbox/templates; omit tags and digests. The builder generates a UUID for each build and publishes paired rootfs and snapshot images. Once the build succeeds, status.manifestRef contains the immutable oci://registry.example.com/sandbox/templates@sha256:... reference used to restore that build.

Prepare the runtime

Use the fast-sandbox companion images built from the source pinned in manifests/third-party/fast-sandbox.commit. OCI templates require the OverlayBD node daemon, shared state and device mounts, and FAST_SANDBOX_OCI_ENABLED=true on the runtime agent, node daemon, and Fastlet pool. Enable runtime.oci.enabled in the fast-sandbox Helm chart to install the node OCI stack. Follow the upstream OverlayBD OCI deployment guide to configure the pool and its registry credentials.

Configure build credentials

Create a Docker Registry Secret in each template namespace. Set REGISTRY_USER and REGISTRY_PASSWORD to an account with push and pull access:

kubectl -n <template-namespace> create secret docker-registry sandbox-registry-credentials \
  --docker-server=registry.example.com \
  --docker-username="$REGISTRY_USER" \
  --docker-password="$REGISTRY_PASSWORD"

Configure the server to use this Secret; OCI publication requires an explicit Secret name:

[kubernetes]
template_oci_publish_secret = "sandbox-registry-credentials"

The Secret must contain .dockerconfigjson, including credentials for private source and execd images when needed. Anonymous access can use a Secret containing {"auths":{}}. Registry authentication supports anonymous or username/password credentials; identity-token-only credentials are unsupported. Configure the pool's registry credentials separately as described in the upstream deployment guide; the build Secret is not copied into running sandboxes.

Build and use a template

osb template create \
  --image python:3.12 \
  --publish oci://registry.example.com/sandbox/templates \
  --format overlaybd \
  -o json

osb template get <template-id> -o json

Wait for status.phase to become Succeeded, then create a sandbox:

osb sandbox create --template <template-id> --timeout 30m -o json

The server resolves the template ID to the recorded immutable OCI reference, so builds from the same source image remain independent. A repository-only publish target is a build destination; it is not a runnable artifact reference.

OCI publishing requires overlaybd, which remains the default format. For S3-compatible publication, explicitly select native:

osb template create --image python:3.12 --publish s3://bucket/publish --format native -o json

Deleting a template removes its catalog entry and Kubernetes build resource. Registry artifacts remain subject to the registry's retention and garbage collection policies.