Skip to content
This documentation covers kagent while it is in development and can describe unreleased features. For the current release, see the latest docs.

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

Page as Markdown

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

  1. 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
    EOF

    Apply the file to your existing Helm release. The following commands use jq to 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 --wait

    A 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-guest image for your release, or mirror that image into your own registry. A custom build must provide a compatible kagent-sandbox-guest executable 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’s spec.workload.image instead, as described in Choose a tools image.

    ValueDefaultDescription
    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.imageRegistry rewrites 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 create omits --ttl. Durations in the config block take protobuf seconds notation, so 3600s rather than 1h.
    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.
  2. Download the latest kagent CLI.

    curl -sL https://kagent.dev/install | bash

    To 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.

  1. 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.

  2. 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"
    
  3. Check the image against the following requirements, which kagent applies when it runs the image.

    BehaviorWhat it means for your image
    kagent replaces the entrypoint.The image’s own ENTRYPOINT and CMD do 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 /data is hidden by the mount. Install programs and files elsewhere, such as under /opt or /usr/local.
    Commands start in /data/workspace.The guest creates /data/workspace and /data/guest-logs before 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.

  1. 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/
    EOF

    Review the following table to understand this configuration. For the complete schema, see the API reference.

    FieldRequiredDescription
    workload.imageYesThe tools image, pinned by sha256 digest, in the <image>@sha256:<digest> form. The API server rejects a reference without a digest, with the message spec.workload.image in body should match '^[^[:space:]@]+@sha256:[a-f0-9]{64}$'.
    envNoEnvironment variables for every process in the Sandbox. This example sets LANG=C.UTF-8 to select a UTF-8 locale for programs that read the locale setting, so they can handle non-ASCII text consistently. Each entry sets a literal value, which is required and can be an empty string. A template cannot read a value from a Secret, and the API server rejects a credentialRef entry as an unknown field. To give a Sandbox a credential, inject it at the egress gateway instead.
    substrate.workerPoolRef.nameYesThe WorkerPool in the template’s namespace that runs the Sandboxes. The pool also decides the sandbox class, such as gVisor.
    substrate.snapshotPolicy.locationYesThe 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.
    egressPolicyRefsNoUp 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.
  2. 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 prepared
    
    ReasonWhat 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.
  3. Confirm that callers can see the template.

    kagent sandbox templates

    Example 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.

Next steps