StackShift Sandbox overview

StackShift Sandbox is isolated, programmable compute for coding agents, interpreters, CI, browser automation, plugins, data jobs, customer code, playgrounds, and disposable development environments. Every product uses the same public resources instead of a product-specific runtime.

Before you begin

You need a StackShift account, a token with sandbox permissions, and a digest-qualified OCI template supported by the configured deployment server. The public contract has no region, zone, node, or deployment-target selector: admission uses StackShift’s configured server and evaluates account quota, server capacity, runtime health, image compatibility, and policy. For CLI use, authenticate interactively or supply a CI token:

stackshift auth login
stackshift auth status

export STACKSHIFT_TOKEN="<token>"
stackshift --output json sandbox list

Never place tokens in command arguments, repository files, or shell history.

Quick start with the CLI

Create calls are asynchronous. --wait follows the durable operation; increase the global timeout for provisioning rather than repeatedly submitting create.

export TEMPLATE='ghcr.io/acme/polyglot-agent@sha256:<64-hex-digest>'

stackshift --timeout 10m --output json sandbox create \
  --name agent-session-42 \
  --sandbox-profile coding_agent \
  --template "$TEMPLATE" \
  --tags agent,customer-acme \
  --wait

List the sandbox, inspect its effective policy, then run a command without an implicit shell:

stackshift sandbox list --state ready
stackshift --output json sandbox get <sandbox-id>
stackshift sandbox exec <sandbox-id> -- node --version

Open a terminal, sleep the sandbox when idle, and resume it later:

stackshift sandbox terminal <sandbox-id> --cwd /workspace
stackshift --timeout 5m sandbox sleep <sandbox-id> --wait
stackshift --timeout 5m sandbox resume <sandbox-id> --wait

destroy is permanent and requires --yes. Retain required output in an artifact, persistent volume, or ready snapshot first.

Understand the resources

Resource	Purpose	Persistence rule
Sandbox	Desired configuration, effective policy, lifecycle, and runtime identity	Exists until destroyed or expired
Execution	One bounded command with state, exit data, and offset-based logs	Metadata and retained logs follow account policy
Process	Reconnectable background command with readiness and signal controls	Process memory does not survive sleep
Terminal	Reconnectable PTY accessed with a short-lived scoped ticket	Session ends when runtime stops
File	Path-safe content under an allowed mount	Depends on the mount that contains it
Port	Explicit authenticated preview for a listening process	Inbound access is otherwise disabled
Artifact	Checksum-verified retained output	Retained independently under artifact policy
Volume	Encrypted, capacity-limited ext4 storage	Persists independently until deleted
Snapshot	Integrity-checked filesystem or volume-group recovery point	Retained until policy or explicit deletion
Secret	Write-only encrypted value with safe metadata	Plaintext is never returned after creation
Service	Managed PostgreSQL, MySQL, or Redis sidecar with an owned encrypted volume	Lifecycle is explicit; deletion removes its data volume
Operation	Durable record for a long-running mutation	Poll or stream until terminal

Read lifecycle correctly

The desired state (running, sleeping, or destroyed) records intent. The observed state records reconciliation and may move through queued, scheduling, provisioning, starting, ready, sleeping, resuming, stopping, destroying, degraded, or failed. Do not treat a successful HTTP response as completed work. Mutations return an operation with status, step, attempt counters, deadline, retryability, and optional failure details. Follow it until succeeded, failed, or cancelled. If the client disconnects, retrieve the operation by ID; retry the original mutation only with the same idempotency key.

Find controls in the dashboard

The Sandboxes landing page is the fleet view. Its local navigation opens global inventories for templates/images, snapshots, volumes, secrets, webhooks, usage/quotas, and audit history. These resources do not crowd the main product sidebar. Inside one sandbox, use:

Area	What belongs there
Overview	Health, effective resources, readiness, active operation, deadlines, cost/usage when authoritative, and recent activity
Workspace, Terminal, Agents, Interpreter, Browser	Interactive work and product-specific projections over public runtime resources
Executions and Processes	One-shot/background command history, state, logs, timing, and failure detail
Ports and Services	Explicit previews/readiness and temporary PostgreSQL/MySQL/Redis dependencies
Storage and Snapshots	Filesystem usage, volumes, retention, restore, and fork
Resource, lifecycle, network, and secret settings	Requested policy alongside normalized effective policy and capability decisions
Metrics, Logs, Events, Usage, and Audit	Timestamped operational and governance evidence
General and Handoff	Identity/tags, source-only deployment handoff, and consequence-aware destroy

Every route reads server state. Loading, empty, pending, degraded, stale, forbidden, unavailable, failure, reconnecting, and deleted states are distinct; a missing or disabled control is not an authorization boundary.

Choose a product profile

Profiles apply reviewed defaults and limits. The API catalog is the authority for currently admitted values.

Profile	Typical use
`coding_agent`	Interactive code editing and agent work
`autonomous_agent`	Longer unattended agent activity
`interpreter`	Stateful Python, JavaScript, or TypeScript contexts
`data_job`	Bounded data-processing commands
`playground`	Interactive disposable environments
`ci`	Build and test execution
`plugin`	Untrusted plugin execution with restrictive egress
`browser`	Browser automation and retained test artifacts
`customer_code`	Customer-generated code execution
`development`	Disposable development environments and snapshot forks

Continue

Workspace and product runs

Run commands, terminals, agents, and interpreters.

CLI reference

Use every supported sandbox CLI command.

API and SDKs

Build against the versioned public contract.

Security and persistence

Understand isolation, limits, secrets, sleep, and snapshots.

​Before you begin

​Quick start with the CLI

​Understand the resources

​Read lifecycle correctly

​Find controls in the dashboard

​Choose a product profile

​Continue

Workspace and product runs

CLI reference

API and SDKs

Security and persistence

Before you begin

Quick start with the CLI

Understand the resources

Read lifecycle correctly

Find controls in the dashboard

Choose a product profile

Continue