> ## Documentation Index > Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt > Use this file to discover all available pages before exploring further. # StackShift Sandbox overview > Create and operate isolated Kata environments through the dashboard, CLI, REST API, or typed SDKs. 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: ```bash theme={null} stackshift auth login stackshift auth status ``` ```bash CI theme={null} export STACKSHIFT_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. ```bash theme={null} 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: ```bash theme={null} stackshift sandbox list --state ready stackshift --output json sandbox get stackshift sandbox exec -- node --version ``` Open a terminal, sleep the sandbox when idle, and resume it later: ```bash theme={null} stackshift sandbox terminal --cwd /workspace stackshift --timeout 5m sandbox sleep --wait stackshift --timeout 5m sandbox resume --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 Run commands, terminals, agents, and interpreters. Use every supported sandbox CLI command. Build against the versioned public contract. Understand isolation, limits, secrets, sleep, and snapshots.