Sandbox CLI reference

All sandbox commands are under stackshift sandbox. They use the same public /api/v1 contract as the dashboard and SDKs.

Authentication and global options

stackshift auth login
stackshift auth status
stackshift sandbox --help

The CLI resolves the active profile, then STACKSHIFT_TOKEN or its configured token. For CI, prefer a mode-0600 token file or stdin over a command argument.

Option	Default	Purpose
`--profile`	active profile	Select stored API/auth configuration
`--api-url`	profile URL	Override the StackShift API host
`--output`, `-o`	`table`	`table`, `json`, `yaml`, or `name`
`--token-file`	none	Read a token from a mode-0600 file
`--token-stdin`	false	Read a CI token from stdin
`--timeout`	`30s`	Bound HTTP requests and `--wait`
`--yes`, `-y`	false	Confirm destructive actions
`--quiet`, `-q`	false	Suppress progress output
`--color`	`auto`	`auto`, `always`, or `never`
`--debug`	false	Show request diagnostics; review before sharing

--project, --app, and --environment are global StackShift selectors but are not substitutes for explicit sandbox IDs.

Sandbox lifecycle

Command	Important options	Result
`sandbox list`	`--state`, `--sandbox-profile`, `--cursor`, `--limit`	Cursor page or table of sandboxes
`sandbox get SANDBOX`	output options	Sandbox and normalized effective policy
`sandbox create`	required `--name`, `--template`; profile defaults to `coding_agent`; optional `--tags`, `--wait`	Durable create operation
`sandbox start SANDBOX`	`--wait`	Start operation
`sandbox sleep SANDBOX`	`--wait`	Sleep operation
`sandbox resume SANDBOX`	`--wait`	Resume operation
`sandbox recover SANDBOX`	`--wait`	Recovery operation when recovery is available
`sandbox destroy SANDBOX`	global `--yes`; optional `--wait`	Permanent destroy operation
`sandbox events SANDBOX`	`--after-sequence`	Resumable JSON event stream
`sandbox operation OPERATION`	`--wait`	Current or terminal operation

create --template requires a digest-qualified OCI reference. The CLI sends a generated idempotency key for each mutation. If a CLI process is interrupted after submission, use the printed operation ID instead of issuing a second create.

stackshift --output json sandbox operation <operation-id>
stackshift --timeout 15m sandbox operation <operation-id> --wait

Execute and connect

stackshift sandbox exec SANDBOX [flags] -- COMMAND [ARG...]

Flag	Default	Meaning
`--cwd`	`/workspace`	Working directory inside an allowed mount
`--user`	`sandbox`	Template-allowed OS user
`--command-timeout`	`600`	Remote timeout in seconds
`--shell`	false	Interpret the joined command with the template shell
`--background`	false	Return the execution resource instead of streaming

The separator -- prevents remote arguments from being parsed as StackShift flags. Without --shell, argv is executed literally. With --shell, quoting and expansion are the caller’s responsibility.

stackshift sandbox exec <sandbox-id> -- python -m pytest -q
stackshift sandbox exec <sandbox-id> --shell -- 'npm test && npm run build'

Interactive terminal syntax:

stackshift sandbox terminal SANDBOX \
  [--cwd /workspace] [--user sandbox] [--rows 24] [--columns 80]

The terminal command obtains a writer lease and scoped ticket. It does not expose or persist those credentials.

Snapshots

Command	Required/important options
`sandbox snapshots list [SANDBOX]`	global list supports `--cursor`, `--limit`
`sandbox snapshots get SNAPSHOT`	none
`sandbox snapshots create SANDBOX`	`--name`; `--type filesystem\|group`; `--retention-seconds` default `86400`; `--wait`
`sandbox snapshots restore SNAPSHOT SANDBOX`	target must sleep; `--safety-snapshot` defaults true; `--wait`
`sandbox snapshots fork SNAPSHOT`	`--name`, `--template`; profile defaults to `development`; `--wait`
`sandbox snapshots delete SNAPSHOT`	global `--yes`; optional `--wait`

stackshift --timeout 15m sandbox snapshots create <sandbox-id> \
  --name release-candidate \
  --type filesystem \
  --retention-seconds 604800 \
  --wait

Do not restore from pending, creating, failed, deleting, or deleted. Inspect integrity, compatibility, encryption, lineage, and volatile_secrets_excluded on the snapshot.

Volumes

Command	Required/important options
`sandbox volumes list [SANDBOX]`	global list supports `--cursor`, `--limit`
`sandbox volumes get VOLUME`	none
`sandbox volumes create SANDBOX`	`--name`, `--kind persistent\|sidecar`, absolute `--mount-path`, positive `--capacity-bytes`; optional `--read-only`, `--wait`
`sandbox volumes grow VOLUME`	larger `--capacity-bytes`; optional `--wait`
`sandbox volumes attach VOLUME SANDBOX`	absolute `--mount-path`; optional `--read-only`, `--wait`
`sandbox volumes detach SANDBOX VOLUME`	sandbox must sleep; optional `--wait`
`sandbox volumes delete VOLUME`	volume must detach; global `--yes`; optional `--wait`

stackshift --timeout 10m sandbox volumes create <sandbox-id> \
  --name workspace-data \
  --kind persistent \
  --mount-path /workspace/data \
  --capacity-bytes 21474836480 \
  --wait

Capacity is a hard byte limit. Grow requests must increase it; shrinking is unsupported.

Temporary services

Command	Required/important options
`sandbox services list SANDBOX`	none
`sandbox services get SANDBOX SERVICE`	none
`sandbox services create SANDBOX`	`--name`; `--engine postgres\|mysql\|redis`; `--capacity-gib` default `10`; `--wait`
`sandbox services start SANDBOX SERVICE`	`--wait`
`sandbox services sleep SANDBOX SERVICE`	`--wait`
`sandbox services delete SANDBOX SERVICE`	global `--yes`; optional `--wait`

Service deletion also deletes its encrypted sidecar data volume. List/get output contains safe connection metadata, never the generated credential URL.

Secrets and bindings

Command	Required/important options
`sandbox secrets list`	safe metadata only
`sandbox secrets get SECRET`	safe metadata only
`sandbox secrets create`	plaintext stdin; `--name`; optional `--type`, `--description`, `--allowed-hosts`
`sandbox secrets rotate SECRET`	new plaintext stdin
`sandbox secrets revoke SECRET`	global `--yes`
`sandbox secrets bindings SANDBOX`	safe binding metadata
`sandbox secrets bind SANDBOX SECRET`	`--scope`, `--target`, `--delivery proxy\|file\|env`, optional `--allowed-hosts`
`sandbox secrets unbind SANDBOX BINDING`	global `--yes`

printf '%s' "$API_TOKEN" | stackshift sandbox secrets create \
  --name upstream-api \
  --type token \
  --allowed-hosts api.example.com

Avoid echo because implementations can add a newline or interpret escapes. The CLI never prints submitted plaintext.

Automation rules

Use --output json and parse fields, not human tables.
Retain operation IDs before waiting.
Set --timeout to the expected operation duration.
Page while has_more is true using next_cursor.
Resume events from the last committed sequence.
Treat timeouts and transport failures as unknown outcomes.
Never automate --yes without a prior inventory and exact resource IDs.

API and SDKs

Use the same contract programmatically.

Troubleshooting

Interpret errors and recover safely.

Overview

API Reference

AI Sandboxes

Introduction

StackShift CLI

Getting Started

Assets

StackShift Mail

Durable Jobs

Projects

Applications

Workload Security

Stacks

Templates

WordPress

Ghost

Shopify Hosting

Nodes

Databases

Operations

Domains & Email

Terminal & Operations

Mobile Distribution

Team & Access

Billing

AI Features

S2 Object Storage

Infrastructure as Code

Settings

Sandbox CLI reference

Authentication and global options

Sandbox lifecycle

Execute and connect

Snapshots

Volumes

Temporary services

Secrets and bindings

Automation rules

API and SDKs

Troubleshooting

​Authentication and global options

​Sandbox lifecycle

​Execute and connect

​Snapshots

​Volumes

​Temporary services

​Secrets and bindings

​Automation rules

API and SDKs

Troubleshooting

Authentication and global options

Sandbox lifecycle

Execute and connect

Snapshots

Volumes

Temporary services

Secrets and bindings

Automation rules