For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.
Set up sandbox templates
Turn on Sandboxes in your installation, choose a tools image, and create the SandboxTemplate that every Sandbox starts from.
A SandboxTemplateSandboxTemplateA kagent custom resource that prepares a reusable runtime with a tools image, environment variables, WorkerPool, snapshot storage, and egress policy references. Sandboxes are created from this template.Learn more defines the tools environment that a Sandbox starts from. It names a tools image, the WorkerPoolWorkerPoolA Kubernetes custom resource declaring how many Workers to keep running and which sandbox class they use. An operator must provision one before any Agent can compile.Learn more that runs it, and the network access that it gets. An operator creates templates, and a caller picks one by namespace and name when it creates a Sandbox. This page shows how to set up the installation for Sandboxes, choose an image, and create a template.
Before you begin
Install kagent, then save the following settings in
sandbox-values.yaml. Sandbox preparation needs a guest image. The chart does not ship a default guest image, so a SandboxTemplate does not become ready until you set one. The remaining values allocate the compute that each Sandbox runs on and bound how long it lives.cat > sandbox-values.yaml <<'EOF' config: sandboxes: guestImage: ghcr.io/kagent-dev/kagent/sandbox-guest@sha256:354825706868fc4d39300fe7795f4fa04d1eb53c3c93fb5b65b5da76f8222db7 cpu: "1" memory: 1Gi defaultTtl: 3600s maxTtl: 86400s EOFApply the file to your existing Helm release. The following commands use
jqto read the installed chart version, so the upgrade preserves both that version and the release’s other values.export KAGENT_CHART_VERSION=$(helm list -n kagent -o json \ | jq -er '.[] | select(.name == "kagent") | .chart | ltrimstr("kagent-")') helm upgrade kagent \ oci://ghcr.io/kagent-dev/kagent/helm/kagent \ --namespace kagent --version "$KAGENT_CHART_VERSION" \ --reuse-values -f sandbox-values.yaml --waitA SandboxTemplate cannot override these values, so they apply to every Sandbox in the installation.
The guest image provides kagent’s process and file service. Use the published
kagent/sandbox-guestimage for your release, or mirror that image into your own registry. A custom build must provide a compatiblekagent-sandbox-guestexecutable at/usr/local/bin/kagent-sandbox-guest, including its readiness endpoint and process and file APIs. A custom build is useful when you maintain a patched guest. An arbitrary Python or Node.js image cannot replace it. To add interpreters, packages, or command line tools for a task, customize the SandboxTemplate’sspec.workload.imageinstead, as described in Choose a tools image.Value Default Description config.sandboxes.guestImage""Required. The complete, digest-pinned reference to the image that supplies kagent’s guest service, as described above. The controller passes the reference to Agent Substrate unchanged and does not resolve tags, so pin a digest. Setting global.imageRegistryrewrites the registry host of this reference.config.sandboxes.cpu1CPU allocated to each Sandbox. config.sandboxes.memory1GiMemory allocated to each Sandbox. config.sandboxes.defaultTtl3600sLifetime applied when kagent sandbox createomits--ttl. Durations in theconfigblock take protobuf seconds notation, so3600srather than1h.config.sandboxes.maxTtl86400sUpper bound on any requested lifetime, which the controller caps at 86400s. A Sandbox expires the configured interval after it is created, regardless of how recently a command ran in it.Download the latest kagent CLI.
curl -sL https://kagent.dev/install | bashTo install a particular version instead, run
curl -sL https://kagent.dev/install | bash -s -- --version v1.0.0.
Choose a tools image
Each Sandbox needs a container image with all of the tools, or programs, that the Sandbox can run, such as an interpreter, a compiler, or a command line tool. kagent adds its own guest program to every Sandbox to serve process and file operations, so the tools image needs nothing else. You can use a public image as it is, or build your own.
Pick a public image such as Python, or build an image that already contains every program that the Sandbox needs. A Sandbox has no outbound network access by default, so a command cannot install a missing package at run time unless you grant network access.
Look up the image’s digest. The API server rejects an image that is referenced by a tag alone, because each prepared revision must be reproducible. For a multi-architecture image, use the digest of the image index, so that each node pulls the variant for its own architecture.
docker buildx imagetools inspect python:3.13-slim --format '{{json .Manifest.Digest}}'Example output:
"sha256:e48f59cdba69a3cbd9ed2cf0f348d90d45a8d350d98134cf1070bc106ee9ed90"Check the image against the following requirements, which kagent applies when it runs the image.
Behavior What it means for your image kagent replaces the entrypoint. The image’s own ENTRYPOINTandCMDdo not run. A SandboxTemplate does not take a startup command, so start any process that a task needs through a process call.kagent mounts a durable volume at /data.Anything that the image places under /datais hidden by the mount. Install programs and files elsewhere, such as under/optor/usr/local.Commands start in /data/workspace.The guest creates /data/workspaceand/data/guest-logsbefore the Sandbox reports ready. If the image runs as a user other than root, that user must be able to write to/data.The Workers must be able to pull the image. If the image is in a private registry, configure the pull credentials for the WorkerPool’s nodes.
Create a SandboxTemplate
A SandboxTemplate is a namespaced kagent custom resource that describes a reusable runtime for Sandbox instances.
Create a SandboxTemplate. The following example uses the Python image from the previous section.
kubectl apply -f - <<EOF apiVersion: api.kagent.dev/v1alpha3 kind: SandboxTemplate metadata: name: python namespace: kagent spec: workload: image: docker.io/library/python:3.13-slim@sha256:e48f59cdba69a3cbd9ed2cf0f348d90d45a8d350d98134cf1070bc106ee9ed90 env: - name: LANG value: C.UTF-8 substrate: workerPoolRef: name: kagent-default snapshotPolicy: location: s3://ate-snapshots/kagent/ EOFReview the following table to understand this configuration. For the complete schema, see the API reference.
Field Required Description workload.imageYes The tools image, pinned by sha256digest, in the<image>@sha256:<digest>form. The API server rejects a reference without a digest, with the messagespec.workload.image in body should match '^[^[:space:]@]+@sha256:[a-f0-9]{64}$'.envNo Environment variables for every process in the Sandbox. This example sets LANG=C.UTF-8to select a UTF-8 locale for programs that read the locale setting, so they can handle non-ASCII text consistently. Each entry sets a literalvalue, which is required and can be an empty string. A template cannot read a value from a Secret, and the API server rejects acredentialRefentry as an unknown field. To give a Sandbox a credential, inject it at the egress gateway instead.substrate.workerPoolRef.nameYes The WorkerPool in the template’s namespace that runs the Sandboxes. The pool also decides the sandbox class, such as gVisor. substrate.snapshotPolicy.locationYes The object storage location for the Sandbox’s snapshotsSnapshotThe stored state that an Actor suspends to, held in object storage. Resuming restores the Actor from its most recent snapshot, which is what makes suspending idle agents cheap.Learn more. egressPolicyRefsNo Up to 16 EgressPolicy resources in the template’s namespace that grant the Sandbox outbound access. When this field is omitted, the Sandbox has no outbound access. Confirm that the template is ready. kagent builds a snapshot of the template’s runtime before it reports
Ready, which can take a minute the first time that a Worker pulls the image.kubectl get sandboxtemplate python -n kagent \ -o jsonpath='{range .status.conditions[?(@.type=="Ready")]}{.status} {.reason} {.message}{end}'Example output:
True Prepared Sandbox runtime is preparedReason What it means Preparingkagent is still building the snapshot. Wait, then check again. PreparedThe template is ready, and callers can create Sandboxes from it. ActorTemplateRetryingThe snapshot build failed, and kagent retries it after 15 seconds, 1 minute, 4 minutes, and then every 10 minutes. The message names the failure reason, the retry number, and its time, such as golden build failed (GoldenActorCrashed), retry 1 at 2026-11-18T21:05:03Z. Common causes are an image that the Workers cannot pull and a missing or wrong guest image. For the full error, read the controller logs.Confirm that callers can see the template.
kagent sandbox templatesExample output:
NAMESPACE NAME IMAGE kagent python docker.io/library/python:3.13-slim@sha256:e48f59cdba69a3cbd9ed2cf0f348d90d45a8d350d98134cf1070bc106ee9ed90
Grant network access
A Sandbox cannot open any outbound connection until its template selects an EgressPolicy. Inside the Sandbox, a destination that no policy allows does not resolve, so a client reports a name-resolution error. For example, Python reports Name or service not known.
To allow a destination, create and attach an egress policy in the template’s namespace. Use the “Standalone sandbox” tab in that procedure to add the policy to spec.egressPolicyRefs on the python template. A policy change applies to running and suspended Sandboxes without recreating them.
Update or delete a template
When you edit a template, kagent prepares a new revision. New Sandboxes use the new revision after it is ready, and existing Sandboxes keep the revision that they were created from. If the new revision fails to prepare, callers keep creating Sandboxes from the last revision that succeeded.
When you delete a template, callers can no longer create Sandboxes from it. Sandboxes that already exist keep running until they are deleted or expire.