Skip to content

Sandbox spec#

Flags cover the flat fields. Anything nested — the sandbox's own embedded policy, its own credentials, its files, pre-start scripts, and tools, image updates — is only expressible in a spec file.

# The REST body is the same document in JSON, except that policies
# are referenced by UUID in `policyIds` rather than by name, and the
# timers are whole minutes in `autoStopMinutes` and `autoDeleteMinutes`.
curl -fsS -X POST \
  -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  https://agents.example.com/v1/projects/$PROJECT_ID/sandboxes \
  -d @sandbox.json
Create a sandbox in production from the spec in ./sandbox.yaml.

create_sandbox accepts the embedded policy and credentials blocks, so an agent can apply a whole spec in one call.

nexusctl sandbox init > sandbox.yaml
nexusctl sandbox create --project production -f sandbox.yaml

sandbox init writes a commented template. -f - reads the spec from stdin. Flags override whatever the file sets, so one file plus --image covers per-environment differences.


Example spec#

image: ghcr.io/acme/agent:1.2
command: python agent.py
cpu: 500m
memory: 2Gi

env:
  LOG_LEVEL: debug

# Who the agent runs as, and where it starts. Omit both to keep the
# image's USER, and WORKSPACE_PATH from env or else the image's WORKDIR.
user: agent
workdir: /work

# Written into the container before the agent starts, on every start.
files:
  - path: /work/AGENTS.md
    content: |
      Run the test suite before you open a pull request.

# Installed with mise before the scripts and the agent, first on PATH.
tools:
  - node@22.11.0
  - jq@1.7.1

# Run in order before the agent starts. The first failure stops the sandbox.
scripts:
  - when: pre-start
    description: Install dependencies
    run: cd /work && npm ci

# A persistent volume, at most one. size is optional.
volumes:
  - mountPath: /work
    size: 5Gi

# Follow the image's tag, and roll a new digest out automatically.
imageUpdate:
  auto: true

# Shared policies to attach, by name or UUID. Each must already be an org
# policy or a policy in this project.
policies:
  - agent-base

# Ports published at <name>--<slug>.<sandbox-ingress-host>. The first entry
# also answers at <slug>.<sandbox-ingress-host>.
exposedPorts:
  - name: web
    port: 8080
    auth: private

healthCheck:
  type: http
  http:
    path: /healthz
    port: 8080
  # Longer than the pre-start scripts take.
  initialDelaySeconds: 300

# Stop after 30 idle minutes, start again on demand, delete a day after
# the sandbox stops.
autoStop: 30m
autoStart: true
autoDelete: 1d

# The sandbox's own policy — private to this sandbox, never listed in the
# shared catalog, deleted with it.
policy:
  name: agent
  allowedDomains:
    - pattern: api.github.com
      verdict: allow
      transport: upstream
  credentials:
    - credentialName: github-token
      envVarKey: GITHUB_TOKEN
  managedInference:
    enabled: true
    provider: bedrock

# Credentials owned by this sandbox. Values are write-only.
credentials:
  github-token:
    value: ${GITHUB_TOKEN}
    injections:
      - domain: api.github.com
        headerName: Authorization
        headerFormat: "Bearer {value}"

Fields#

Required#

Field Type Notes
image string OCI image reference for the agent container.
command string Run through sh -c by the supervisor.
cpu string Kubernetes quantity. Capped by the install ceiling.
memory string Kubernetes quantity. Capped by the install ceiling.

Optional#

Field Type Notes
name string Human-friendly display name. The immutable slug is assigned by the platform.
env map Environment variables for the container.
labels map Free-form labels for your own grouping and queries.
user string USER or USER:GROUP, each a name from the image or a numeric id. A name the image lacks stops the sandbox from starting.
workdir string Absolute directory the agent, exec, and the terminal start in. Created for the agent's user when the image lacks it.
files list Text files, each path (absolute) and content, written with mode 0644 before the agent starts. See Files and pre-start scripts.
scripts list Pre-start scripts, each when: pre-start, run, and optional user and description. See Files and pre-start scripts.
tools list Up to 32 tools as name@version, such as jq@1.7.1, each a mise registry name with no backend prefix. Installed from prebuilt releases before the pre-start scripts and the agent, on every start, and first on the PATH of the agent, exec, and the scripts. A tool that cannot be installed stops the sandbox. See Tools.
volumes list At most one entry, mountPath and an optional size. See Storage and health.
exposedPorts list At most four entries, each with its own auth: private, public, or webhook. See Exposed ports.
healthCheck object HTTP probe. See Storage and health.
policies list Shared policies to attach, by name or UUID.
policy object This sandbox's own embedded policy.
credentials map This sandbox's own embedded credentials.
autoStop duration Stop after this long with no exec, terminal, private-port, or model-call activity. 30m, 2h, 7d, up to 30 days. See timers.
autoDelete duration Delete, with the volume, this long after the sandbox was asked to stop. 0 deletes it as soon as it has stopped. Up to 30 days.
autoStart boolean Start again when an exec, terminal, or private-port request reaches a sandbox that autoStop stopped.
imageUpdate object {auto: false} reports a new digest behind the image's tag; {auto: true} also rolls it out. At create, null or absent is off. On an update, null turns it off and an absent imageUpdate is kept. See Image updates.

user, workdir, files, scripts, and tools are part of the revision: a change restarts the sandbox, and a rollback restores them. In a spec applied with nexusctl sandbox update -f, user: null or workdir: null goes back to the default, and [] removes the files, scripts, or tools. A larger volumes[].size grows the volume without a restart; see Persistent volumes.

In a spec applied with nexusctl sandbox update -f, autoStop: null or autoDelete: null turns that timer off, and a timer the file leaves out is kept.


Shared policies versus the embedded policy#

Both grant the sandbox access. They differ in ownership and reuse.

policies: policy:
Lives in The project or org policy catalog The sandbox
Reused by Any sandbox that names it Nothing — it is private
Visible in nexusctl policy list sandbox describe only
Deleted when You delete the policy You delete the sandbox

Use policies: for the rules a fleet shares — the base egress allowlist, the managed-inference grant. Use policy: for the one domain this particular agent needs and nothing else does.

Both merge into the sandbox's effective policy, under the org policy ceiling. See Policies.


Embedded credentials#

credentials:
  github-token:
    value: ${GITHUB_TOKEN}
    injections:
      - domain: api.github.com
        headerName: Authorization
        headerFormat: "Bearer {value}"

${VAR} is expanded from your environment after the file is parsed, so the file stays committable and the secret needs no quoting or escaping.

Values are write-only. The API never returns them, and nexusctl sandbox export omits them.

The agent never receives the real secret. It sees a placeholder; the sandbox's egress proxy substitutes the real value into the named header on requests to the named domain. See Credentials.

A credential can also be minted instead of stored: oauthClientCredentials for the OAuth client-credentials grant, or jwtAssertion for a GitHub App. Set exactly one of value, oauthClientCredentials, and jwtAssertion.

policy:
  name: agent
  allowedDomains:
    - pattern: api.github.com
      verdict: allow
      transport: upstream
    - pattern: github.com
      verdict: allow
      transport: upstream
  credentials:
    - credentialName: github
      envVarKey: GH_TOKEN

credentials:
  github:
    jwtAssertion:
      preset: github
      clientId: Iv23liExampleClientId
      privateKey: ${GITHUB_APP_PRIVATE_KEY}
      installationId: 12345678
      repositories:
        - web-app
      permissions:
        contents: write
        pull_requests: write

The platform signs a JWT with the private key and mints installation tokens limited to those repositories and permissions. With no injections, the tokens go into requests to api.github.com and github.com. As with any credential, the policy must grant it and allow both hosts. With the placeholder in GH_TOKEN, gh and git over HTTPS work in the sandbox. The private key and the tokens never reach the sandbox.

A minted credential is added once. When it already exists, nexusctl sandbox update -f with the same spec is refused with Embedded credential "github" exists. To change it, remove it in one update (github: null), then add it again in the next, together with its policy.credentials grant: removing a credential also removes its grant from the sandbox's policy. To re-apply a spec without changing the credential, leave its credentials block out.


Files and pre-start scripts#

Files are written after the sandbox's policy arrives and before the agent starts, on every start of the sandbox, and not again while it runs, so what the agent changes in them stays until the next start. Missing directories are created with mode 0755. Files and directories belong to the agent's user, so a path that user cannot write to stops the sandbox. The platform never deletes a file: one removed from the spec is only no longer written.

At most 256 files, 128 KiB each and 1 MiB in total, with a path of at most 4096 bytes and no part over 255 bytes. A file name that looks like a secret, such as .env, *.pem, or id_rsa, is refused: secrets go in as credentials.

Scripts run after the files are written and the policy is in force, so they reach the network through the same proxy and policy as the agent. They run in order, each with sh -e, with the agent's environment, no stdin, and their user's home directory as the working directory. A script runs as the agent's user unless it names another user. Each script's output appears in the sandbox logs under [scripts n/N].

The first script that fails stops the sandbox, and the agent does not start. Scripts have no timeout, but on Kubernetes an HTTP health check counts from the start of the container: give its initialDelaySeconds longer than the scripts take. At most 32 scripts, 128 KiB each and 512 KiB in total. Script text is returned with the sandbox, so keep secrets out of it.

A sandbox that comes back after its main command finished writes no files and runs no scripts. Files and scripts need the sandbox supervisor image of 0.32.0 or later; an older supervisor is refused and the sandbox stops.


Tools#

tools:
  - node@22.11.0
  - jq@1.7.1

Each entry is name@version: a mise registry name with no backend prefix, so jq@1.7.1 and not aqua:jqlang/jq@1.7.1. The version can be latest. At most 32 tools, each name only once.

Tools are installed on every start, before the files, the pre-start scripts, and the agent. Only prebuilt releases install: backends that build or run code on install, such as npm, cargo, and pipx, are off. Each tool goes first on the PATH of the agent, of exec sessions, and of the pre-start scripts. The install output appears in the sandbox logs under [tools n/N].

Tools are read-only to the agent. A command that installs into a tool's own prefix fails, such as npm install -g with a declared node, or pip install into a declared python. Install into the agent's home instead, with npm_config_prefix, pip install --user, or a virtual environment.

The downloads happen before the sandbox's policy is in force, so they go through the install's tools cache, which allows only known download hosts. A tool from another host fails to install until an administrator adds the host to the Helm value sandbox.toolsCache.extraHosts. See Sandbox runtime.

A failed install is tried three times. Then the sandbox goes to error, with a reason that starts Tool install failed: and names the tool.


Export a running sandbox#

nexusctl sandbox export nightly-refactor --project production > sandbox.yaml

export prints a sandbox as a spec, ready to re-apply with create -f. Timers that are set come out as autoStop, autoDelete, and autoStart, and user, workdir, files, scripts, tools, volumes, and imageUpdate come out as set. This is how you promote a sandbox from staging to production, or check a working configuration into git.

The credentials block is left out, because credential values are write-only. Add it again before you apply the spec to a new sandbox. An update -f with the exported spec keeps the sandbox's credentials. The secret of a webhook port is left out too: an update -f keeps the stored one, and a create -f needs secret: ${VAR} in the spec or --webhook-secret-file.