Secure, Fast, and Extensible Sandbox runtime for AI agents.
name: sandbox-lifecycle description: Use OpenSandbox CLI lifecycle commands to create, inspect, verify, renew, pause, resume, expose, and terminate sandboxes. Also covers template (golden-image) builds and snapshot management. Trigger when users want help provisioning a sandbox, choosing create flags, creating from a template or snapshot, managing templates or snapshots, checking runtime state, retrieving endpoints, or safely cleaning up sandboxes.
OpenSandbox Sandbox Lifecycle
Use OpenSandbox lifecycle commands directly instead of giving generic container advice. Prefer a verified lifecycle flow over isolated commands.
When To Use
- the user wants to create a sandbox for a task or workflow
- the user wants to create a sandbox from a template (golden image) or restore a snapshot
- the user wants to build, inspect, list, or delete templates
- the user needs to inspect sandbox state or health
- the user wants to expose a service port through an OpenSandbox endpoint
- the user wants to renew, pause, resume, or terminate a sandbox
- the user is unsure which create flags or file-based inputs to use
Configuration Resolution
Before giving lifecycle commands, resolve the active OpenSandbox connection configuration:
osb config show -o json
Check the resolved values for:
domainapi_keyprotocoluse_server_proxywhen endpoint routing matters
osb config show redacts the API key. Use it to confirm which server and protocol the CLI will target, not to recover credentials.
Do not focus only on environment variables. osb config show already reflects the effective configuration after applying CLI flags, environment variables, config file values, and defaults.
Hard stop:
osb config show -o json
If domain is missing, stop and set it before lifecycle commands:
osb config set connection.domain <host:port> -o json
osb config show -o json
If auth is required and api_key is missing, stop and set it before lifecycle commands:
osb config set connection.api_key <api-key> -o json
osb config show -o json
If the effective target is clear, then continue with lifecycle commands.
Preflight Checks
Run these checks before lifecycle commands:
osb --version
osb config show -o json
If osb is missing, try a project-local entrypoint:
.venv/bin/osb --version
.venv/bin/osb config show -o json
Use the results to classify the situation:
- CLI available
- config resolves
- target looks plausible for the current environment
Golden Path
Use this as the default lifecycle flow unless the user asks for a narrower action:
osb config show -o json
osb sandbox create --image python:3.12 --timeout 30m -o json
osb sandbox get <sandbox-id> -o json
osb sandbox health <sandbox-id> -o json
If the sandbox is intended to serve traffic on a known port, continue with:
osb sandbox endpoint <sandbox-id> --port 8080 -o json
This sequence is safer than stopping at sandbox get, because get confirms object state while health confirms the sandbox is actually reachable through the execd health path.
Create Options
Start with the narrowest create command that matches the request:
osb sandbox create --image python:3.12 -o json
osb sandbox create --image node:20 --timeout 30m -o json
osb sandbox create --image my-registry.example.com/team/app:latest --image-auth-username alice --image-auth-password <token> -o json
osb sandbox create --image python:3.12 --timeout none -o json
osb sandbox create --image python:3.12 --entrypoint python --entrypoint -m --entrypoint http.server -o json
osb sandbox create --image python:3.12 --extension storage.id=abc123 -o json
osb sandbox create --image python:3.12 --ready-timeout 90s -o json
osb sandbox create --image python:3.12 --network-policy-file network-policy.json -o json
osb sandbox create --image python:3.12 --network-policy-file network-policy.json --credential-proxy -o json
osb sandbox create --image python:3.12 --volumes-file volumes.json -o json
osb sandbox create -f sandbox-request.json -o json
Use these options deliberately:
--image: required unless the CLI already hasdefaults.imageconfigured--image-auth-usernameand--image-auth-password: use together when the image is in a private registry--timeout: recommended for most temporary workloads so sandboxes do not linger indefinitely--timeout none: disable automatic expiration and switch the sandbox to manual cleanup mode- omit
--timeout: usedefaults.timeoutwhen configured; otherwise the request falls back to the SDK/server default TTL --entrypoint: repeat the flag once per argv item; do not use JSON or shell-wrapped command strings--extension: repeat for opaque extension key-value pairs that should be passed through as-is--ready-timeout: increase this when the image or workload needs more startup time--skip-health-check: use only when the user explicitly wants object creation without waiting for readiness; do not use it to mask startup problems--credential-proxy: enable Credential Vault transparent proxy support; requires--network-policy-file--template <tpl-id>: create from aSucceededtemplate; mutually exclusive with--imageand--snapshot-id; requires an explicit--timeout--snapshot-id <snap-id>: restore a sandbox from a snapshot; mutually exclusive with--imageand--template-f <request-file>: read the full request from a JSON file in the publicCreateSandboxRequestwire format (camelCase:image/templateId/snapshotId,timeoutin seconds ornull,resourceLimits,networkPolicy,volumes,lifecycle, ...); mutually exclusive with request-building flags (--skip-health-check,--ready-timeout,-ostill apply). Prefer this when the user already has a request document or needs fields without dedicated flags.
If the user does not specify an image, recommend one that matches the runtime they need instead of guessing silently.
Templates And Snapshots
Templates are golden-image builds. The build is asynchronous: template create returns a template in Pending; poll template get until the phase is Succeeded (or Failed).
osb template create --image python:3.12 --publish s3://bucket/publish --format native -o json
osb template create --image python:3.12 --publish oci://registry.example.com/sandbox/templates --format overlaybd -o json
osb template create -f template-request.json -o json
osb template get <template-id> -o json
osb template list -o json
osb template delete <template-id> -o json
Useful template create options: --resource cpu=1 memory=512Mi disk=2Gi, --entrypoint (repeat per argv item), --env KEY=VALUE, --metadata KEY=VALUE, --format native|overlaybd, --readiness-probe tcp://127.0.0.1:44772, --warmup-seconds 60. -f <request-file> reads the full request as public CreateTemplateRequest JSON (camelCase: image, publish, resourceLimits, entrypoint, env, metadata, format, readiness.probe, readiness.warmupSeconds), mutually exclusive with those flags.
OCI publication requires a repository-only target without a tag or digest, overlaybd format, and a server-configured .dockerconfigjson Secret (kubernetes.template_oci_publish_secret). Sandbox creation also requires an OCI-enabled Fast Sandbox pool and the OverlayBD node daemon. S3 publication uses native. Wait for Succeeded before creating a sandbox; the server uses the immutable OCI manifest reference for OCI templates.
Create a sandbox from a succeeded template:
osb sandbox create --template <template-id> --timeout 30m -o json
Template mode fixes the workload shape on the server: --image, --env, --resource, --entrypoint, --volumes-file, and --credential-proxy cannot be combined with --template. Only --timeout (required), --metadata, --extension, and --network-policy-file may accompany it.
Snapshots capture a running sandbox's memory and disk state and can back new sandboxes:
osb snapshot create <sandbox-id> --name golden -o json
osb snapshot get <snapshot-id> -o json
osb snapshot list --sandbox-id <sandbox-id> -o json
osb snapshot delete <snapshot-id> -o json
osb sandbox create --snapshot-id <snapshot-id> --timeout 30m -o json
Template-based creation requires a Kubernetes-backed fast-sandbox runtime; snapshot flows depend on the runtime supporting checkpoint/restore.
JSON Shapes
When recommending --network-policy-file or --volumes-file, always show the JSON shape instead of assuming the user knows it.
Example network-policy.json:
{
"defaultAction": "deny",
"egress": [
{
"action": "allow",
"target": "pypi.org"
},
{
"action": "allow",
"target": "files.pythonhosted.org"
}
]
}
Example volumes-host.json:
[
{
"name": "workspace-data",
"host": {
"path": "/tmp/opensandbox-data"
},
"mountPath": "/workspace/data",
"readOnly": false
}
]
Example volumes-pvc.json:
[
{
"name": "shared-models",
"pvc": {
"claimName": "shared-models-pvc"
},
"mountPath": "/workspace/models",
"readOnly": true
}
]
Prefer pvc when the environment supports it and the user needs a more portable storage definition. Use host when the user explicitly needs a host-path bind mount and the server has been configured to allow that path.
Verification
Use verification commands in this order:
osb sandbox get <sandbox-id> -o json
osb sandbox health <sandbox-id> -o json
osb sandbox metrics <sandbox-id> -o json
osb sandbox metrics <sandbox-id> --watch -o raw
Use:
sandbox getto inspect the current lifecycle state and metadatasandbox healthto confirm the sandbox is usablesandbox metricsfor a point-in-time resource snapshotsandbox metrics --watchwhen the user wants live CPU and memory updates while diagnosing load or pressure
If the user needs a public or routed port, verify it explicitly:
osb sandbox endpoint <sandbox-id> --port 8080 -o json
Lifecycle Actions
Use these commands for ongoing lifecycle management:
osb sandbox list -o json
osb sandbox list --state running --state paused -o json
osb sandbox renew <sandbox-id> --timeout 30m -o json
osb sandbox pause <sandbox-id> -o json
osb sandbox resume <sandbox-id> -o json
osb sandbox kill <sandbox-id> -o json
Rules:
- use
sandbox listfor discovery or filtering, not single-sandbox verification sandbox list --stateaccepts known lifecycle states case-insensitively- use
renewbefore long-running work instead of waiting for expiry - use
pauseonly when the workload can tolerate suspension - treat the pause result as request acceptance and poll
sandbox getuntil the state isPausedorFailed killreturnsdeletion_requestedwhen accepted; pollsandbox getuntil404to confirm resource removal. PoolNooppreserves processes even after removal.
Runtime Notes
renewresets the expiration to approximatelynow + timeout; treat it as a fresh TTL, not a simple additive extension to the old timestampcreate --timeout nonemeans no automatic expiration; cleanup becomes an explicitkillresponsibilitycreatewithout--timeoutdoes not mean manual cleanup; it usesdefaults.timeoutfirst and otherwise leaves TTL selection to the SDK/server defaultpauseis asynchronous;Pause request accepteddoes not mean the sandbox is already pausedpauseandresumemay depend on the underlying runtime; if the runtime does not support them, avoid promising they will work- only templates in the
Succeededphase can backsandbox create --template; polltemplate getwhile the build isPending/Building sandbox create --templaterequires an explicit finite--timeout;--timeout noneis rejected in template mode- host-path volumes depend on server-side allowed host path configuration
- if creation fails or the sandbox never becomes healthy, switch to
sandbox-troubleshootinginstead of adding more create flags blindly
Response Pattern
Structure the answer as:
- exact command to run
- what state change or verification result to expect
- the next lifecycle command if the workflow continues
Keep command examples concrete and ready to paste.
Minimal Closed Loops
Create and verify readiness:
osb sandbox create --image python:3.12 --timeout 30m -o json
osb sandbox get <sandbox-id> -o json
osb sandbox health <sandbox-id> -o json
Create a service sandbox and retrieve its endpoint:
osb sandbox create --image python:3.12 --timeout 30m -o json
osb sandbox health <sandbox-id> -o json
osb sandbox endpoint <sandbox-id> --port 8080 -o json
Create with network policy:
osb sandbox create --image python:3.12 --network-policy-file network-policy.json -o json
osb sandbox get <sandbox-id> -o json
osb sandbox health <sandbox-id> -o json
Build a template, wait for it, and create from it:
osb template create --image python:3.12 --publish s3://bucket/publish --format native -o json
osb template get <template-id> -o json
osb sandbox create --template <template-id> --timeout 30m -o json
osb sandbox health <sandbox-id> -o json
Snapshot a sandbox and restore it:
osb snapshot create <sandbox-id> --name golden -o json
osb sandbox create --snapshot-id <snapshot-id> --timeout 30m -o json
osb sandbox health <sandbox-id> -o json
Renew before long work:
osb sandbox renew <sandbox-id> --timeout 30m -o json
osb sandbox get <sandbox-id> -o json
Pause and confirm state:
osb sandbox pause <sandbox-id> -o json
osb sandbox get <sandbox-id> -o json
Resume and verify health:
osb sandbox resume <sandbox-id> -o json
osb sandbox health <sandbox-id> -o json
Best Practices
resolve the active connection configuration before assuming which server the command will hit
prefer
osb config showover checking individual environment variables in isolationconfirm whether the user wants to keep, override, or persist connection settings before changing them
Prefer explicit
--imageand--timeoutwhen demonstrating commandsPrefer
healthover assuming readiness fromcreateoutput alonePrefer
endpointover telling the user to guess host/port mappingsPrefer
pvcoverhostwhen portability mattersPrefer troubleshooting over
--skip-health-checkwhen startup is failing