Skip to content

Sandbox spec#

Flags cover the flat fields. Anything nested — the sandbox's own embedded policy, its own credentials — 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.
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

# 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 <slug>.<sandbox-ingress-host>.
exposedPorts:
  - name: web
    port: 8080
    auth: private

healthCheck:
  type: http
  http:
    path: /healthz
    port: 8080

# 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
  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.
volumes list At most one entry today. See Storage and health.
exposedPorts list At most one entry today. 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.

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.

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. This is how you promote a sandbox from staging to production, or check a working configuration into git.

Credential values are omitted, so an exported spec needs its ${VAR} references supplied again at apply time.