Sandbox

Ephemeral sandboxes for agents.

Set LIGHTNING_SANDBOX_API_KEY for non-interactive authentication. The sandbox API uses https://platform.lightning.ai by default; set LIGHTNING_CLOUD_URL to override the host.

Usage:

lightning sandbox [OPTIONS] COMMAND [ARGS]...

Commands

Command	Description
`command`	Show sandbox command status.
`commands`	List a sandbox’s command history.
`connect`	Open an interactive shell in a sandbox.
`create`	Create a sandbox and wait until it is running.
`delete`	Delete a sandbox.
`list`	List sandboxes.
`logs`	Show logs for a sandbox, merged across its commands.
`run`	Run a command in a sandbox.
`snapshot`	Manage Lightning AI Sandbox snapshots.
`start`	Start a stopped persistent sandbox.
`stop`	Stop a sandbox.
`update`	Update a sandbox.

Examples

$ sandbox list --teamspace owner/teamspace --limit 2
┏━━━━━━━━┳━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ ID     ┃ Name   ┃ Status  ┃ Instance type ┃ Persistent ┃
┡━━━━━━━━╇━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ sbx-42 │ devbox │ running │ cpu-1         │ yes        │
└────────┴────────┴─────────┴───────────────┴────────────┘

$ sandbox create --name devbox --teamspace owner/teamspace --persistent
┏━━━━━━━━┳━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ ID     ┃ Name   ┃ Status  ┃ Instance type ┃ Persistent ┃
┡━━━━━━━━╇━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ sbx-42 │ devbox │ running │ cpu-1         │ yes        │
└────────┴────────┴─────────┴───────────────┴────────────┘

$ sandbox run sbx-42 -- python -c "print('hello')"
hello

$ sandbox run sbx-42 --detached -- bash -lc "echo start; sleep 1; echo done"
cmd-abc123

$ sandbox logs sbx-42 cmd-abc123 --no-timestamps
start
done

$ sandbox stop sbx-42
Stopped sandbox sbx-42
Auto snapshot: snap-abc123

lightning sandbox command

Show sandbox command status.

Usage:

lightning sandbox command [OPTIONS] SANDBOX_ID COMMAND_ID

Arguments

Name	Type	Required	Description
`SANDBOX_ID`	`text`	yes	Sandbox ID that owns the command.
`COMMAND_ID`	`text`	yes	Sandbox command ID to inspect.

Options

Option	Type	Required	Default	Description
`--api-key`	`TEXT`	no	`Sentinel.UNSET`	Sandbox API key.
`--json`	—	no	`Sentinel.UNSET`	Print JSON output.

Examples

$ sandbox command sbx-42 cmd-abc123

Command ID: cmd-abc123

Exit code: 0

done

lightning sandbox commands

List a sandbox’s command history.

Usage:

lightning sandbox commands [OPTIONS] SANDBOX_ID

Arguments

Name	Type	Required	Description
`SANDBOX_ID`	`text`	yes	Sandbox ID whose command history should be listed.

Options

Option	Type	Required	Default	Description
`--api-key`	`TEXT`	no	`Sentinel.UNSET`	Sandbox API key.
`--json`	—	no	`Sentinel.UNSET`	Print JSON output.

Examples

$ sandbox commands sbx-42
┏━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┓
┃ Command ID ┃ Running ┃ Exit code ┃ Command ┃ Started at           ┃
┡━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━┩
│ cmd-abc123 │ no      │ 0         │ echo    │ 2026-06-19T18:00:47Z │
└────────────┴─────────┴───────────┴─────────┴──────────────────────┘

lightning sandbox connect

Open an interactive shell in a sandbox.

Streams a PTY session to your local terminal. Type exit or press Ctrl-D to disconnect. Requires an interactive terminal (a TTY) and is only supported on Unix-like systems.

Usage:

lightning sandbox connect [OPTIONS] SANDBOX_ID

Arguments

Name	Type	Required	Description
`SANDBOX_ID`	`text`	yes	No description provided.

Options

Option	Type	Required	Default	Description
`--api-key`	`TEXT`	no	`Sentinel.UNSET`	Sandbox API key.
`--workdir`	`TEXT`	no	`Sentinel.UNSET`	Working directory for the shell inside the sandbox.
`--env`	`TEXT`	no	`['']`	Environment variable in KEY=VALUE or JSON format. Can be passed multiple times.
`--session-name`	`TEXT`	no	—	PTY session name. Defaults to a unique per-invocation name.

Examples

$ sandbox connect sbx-42

$ sandbox connect sbx-42 --workdir /workspace --env MODE=dev

lightning sandbox create

Create a sandbox and wait until it is running.

Pass –connect to drop straight into an interactive shell once the sandbox is running (mutually exclusive with –json).

Pass –docker for a sandbox that can build and run containers (docker / docker compose); the daemon is started for you at boot.

Usage:

lightning sandbox create [OPTIONS]

Options

Option	Type	Required	Default	Description
`--api-key`	`TEXT`	no	`Sentinel.UNSET`	Sandbox API key.
`--name`	`TEXT`	no	`Sentinel.UNSET`	Sandbox name. Defaults to a generated name.
`--instance-type`	`TEXT`	no	`Sentinel.UNSET`	Sandbox instance type. Defaults to cpu-1.
`--runtime`	`TEXT`	no	`Sentinel.UNSET`	Runtime image or runtime identifier.
`--image`	`TEXT`	no	`Sentinel.UNSET`	Custom OCI image for the sandbox rootfs (mutually exclusive with –runtime).
`--image-secret-ref`	`TEXT`	no	`Sentinel.UNSET`	Name of a project Docker-registry Secret used to pull a private –image.
`--docker`	—	no	—	Provision a Docker-enabled sandbox (starts dockerd at boot; selects the runtime’s -docker variant). Mutually exclusive with –image and –snapshot-id.
`--spot`, `--no-spot`	—	no	—	Create the sandbox on spot capacity.
`--port`	`TEXT`	no	`Sentinel.UNSET`	Port to expose. Can be passed multiple times.
`--teamspace`	`TEXT`	no	`Sentinel.UNSET`	Teamspace to own persistent sandbox state (format: owner/teamspace).
`--snapshot-id`	`TEXT`	no	`Sentinel.UNSET`	Snapshot ID to restore from.
`--persistent`, `--ephemeral`	—	no	—	Persist state across stops.
`--timeout`	`INTEGER`	no	`Sentinel.UNSET`	Maximum sandbox lifetime in milliseconds, after which it is auto-stopped (note: this is ms, unlike run –timeout which is seconds).
`--connect`	—	no	`Sentinel.UNSET`	After the sandbox is running, open an interactive shell in it (requires a TTY).
`--json`	—	no	`Sentinel.UNSET`	Print JSON output.

Examples

$ sandbox create --name devbox

devbox

$ sandbox create --name devbox --teamspace owner/teamspace --persistent

devbox

$ sandbox create --name devbox --docker

devbox

$ sandbox create --name devbox --connect

(interactive shell)

$ sandbox create --name devbox --teamspace owner/teamspace --json

{
  "persistent": true
}

lightning sandbox delete

Delete a sandbox.

Usage:

lightning sandbox delete [OPTIONS] SANDBOX_ID

Arguments

Name	Type	Required	Description
`SANDBOX_ID`	`text`	yes	Sandbox ID to delete.

Options

Option	Type	Required	Default	Description
`--api-key`	`TEXT`	no	`Sentinel.UNSET`	Sandbox API key.
`--yes`, `-y`	—	no	—	Delete without prompting for confirmation.

Examples

$ sandbox delete sbx-42

Sandbox deleted

lightning sandbox list

List sandboxes.

Usage:

lightning sandbox list [OPTIONS]

Options

Option	Type	Required	Default	Description
`--api-key`	`TEXT`	no	`Sentinel.UNSET`	Sandbox API key.
`--page-token`	`TEXT`	no	`Sentinel.UNSET`	Pagination token returned by a previous list call.
`--limit`	`INTEGER`	no	`Sentinel.UNSET`	Maximum number of sandboxes to return.
`--teamspace`	`TEXT`	no	`Sentinel.UNSET`	Only list sandboxes in this teamspace (format: owner/teamspace).
`--json`	—	no	`Sentinel.UNSET`	Print JSON output.

Examples

$ sandbox list --teamspace owner/teamspace --limit 2

Next page token: next-page-token

$ sandbox list --teamspace owner/teamspace --json

{
  "total_size": 1
}

lightning sandbox logs

Show logs for a sandbox, merged across its commands.

Omit COMMAND_ID for the merged logs of every command in the sandbox. Shares the same options as job/mmt/deployment logs.

Usage:

lightning sandbox logs [OPTIONS] SANDBOX_ID [COMMAND_ID]

Arguments

Name	Type	Required	Description
`SANDBOX_ID`	`text`	yes	Sandbox ID that owns the command.
`COMMAND_ID`	`text`	no	Sandbox command ID whose logs should be shown.

Options

Option	Type	Required	Default	Description
`--api-key`	`TEXT`	no	`Sentinel.UNSET`	Sandbox API key.
`--follow`, `-f`	—	no	—	Stream new log lines as they are produced.
`--tail`	`INTEGER`	no	—	Only show the last N lines.
`--since`	`TEXT`	no	—	Only include lines at or after this time (e.g. “2h”, RFC3339).
`--until`	`TEXT`	no	—	Only include lines at or before this time (e.g. “30m”, RFC3339).
`--query`	`TEXT`	no	—	Only include lines containing every whitespace-separated term.
`--severity`	`[error\|warning\|info\|debug]`	no	—	Only include lines at or above this severity.
`--timestamps`	—	no	—	Prepend each line with its ISO-8601 timestamp.
`--json`	—	no	—	Output entries as a JSON array.
`--interactive`, `-i`	—	no	—	Launch the interactive TUI log viewer.

Examples

$ lightning sandbox logs sbx-42 --tail 100
$ lightning sandbox logs sbx-42 cmd-abc123 --follow
$ lightning sandbox logs sbx-42 --query error --since 2h

lightning sandbox run

Run a command in a sandbox.

Use – before the sandbox command when that command has its own flags.

Usage:

lightning sandbox run [OPTIONS] SANDBOX_ID COMMAND_ARGS...

Arguments

Name	Type	Required	Description
`SANDBOX_ID`	`text`	yes	Sandbox ID where the command should run.
`COMMAND_ARGS`	`text`	yes	Command and arguments to run in the sandbox.

Options

Option	Type	Required	Default	Description
`--api-key`	`TEXT`	no	`Sentinel.UNSET`	Sandbox API key.
`--cwd`	`TEXT`	no	`Sentinel.UNSET`	Working directory inside the sandbox.
`--env`	`TEXT`	no	`['']`	Environment variable in KEY=VALUE or JSON format.
`--detached`	—	no	`Sentinel.UNSET`	Start the command and return immediately.
`--timeout`	`FLOAT`	no	`Sentinel.UNSET`	Seconds to wait for a detached command.
`--poll-interval`	`FLOAT`	no	`0.5`	Detached command poll interval.
`--json`	—	no	`Sentinel.UNSET`	Print JSON output.

Examples

$ sandbox run sbx-42 -- python -c "print('hello')"

hello

$ sandbox run sbx-42 --cwd /workspace --env MODE=test -- python app.py

app started

$ sandbox run sbx-42 --detached -- bash -lc "echo start; sleep 1; echo done"

cmd-abc123

$ sandbox run sbx-42 --json -- python -c "print('hello')"

{
  "cmd_id": "cmd-abc123",
  "output": "hello\n"
}

lightning sandbox snapshot

Manage Lightning AI Sandbox snapshots.

A snapshot is an immutable, restorable capture of a sandbox’s filesystem. Create one from a running sandbox, then restore it via sandbox create –snapshot-id <id>.

Usage:

lightning sandbox snapshot [OPTIONS] COMMAND [ARGS]...

Commands

Command	Description
`create`	Snapshot a sandbox’s filesystem.
`delete`	Delete a sandbox snapshot.
`get`	Show a sandbox snapshot.
`list`	List sandbox snapshots.

Examples

$ sandbox snapshot create sbx-42
$ sandbox snapshot list --teamspace owner/teamspace
$ sandbox snapshot delete snap-42

lightning sandbox snapshot create

Snapshot a sandbox’s filesystem.

Captures filesystem state only (not running processes). Waits until the snapshot is ready by default; pass –no-wait to return the saving row immediately.

Usage:

lightning sandbox snapshot create [OPTIONS] SANDBOX_ID

Arguments

Name	Type	Required	Description
`SANDBOX_ID`	`text`	yes	Sandbox ID to snapshot.

Options

Option	Type	Required	Default	Description
`--api-key`	`TEXT`	no	`Sentinel.UNSET`	Sandbox API key.
`--expiration`	`INTEGER`	no	`Sentinel.UNSET`	TTL in milliseconds (0 = never). Defaults to the platform default.
`--exclude`	`TEXT`	no	`Sentinel.UNSET`	Path to exclude from the snapshot. Repeatable.
`--wait`, `--no-wait`	—	no	`true`	Wait until the snapshot is ready.
`--wait-timeout`	`FLOAT`	no	`600.0`	Seconds to wait for readiness.
`--json`	—	no	`Sentinel.UNSET`	Print JSON output.

Examples

$ sandbox snapshot create sbx-42
┏━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┳━━━━━━┓
┃ ID      ┃ Status ┃ Source sandbox ┃ Runtime ┃ Size     ┃ Auto ┃
┡━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━╇━━━━━━┩
│ snap-42 │ ready  │ devbox         │ python  │ 12.3 MiB │ no   │
└─────────┴────────┴────────────────┴─────────┴──────────┴──────┘

lightning sandbox snapshot delete

Delete a sandbox snapshot.

Usage:

lightning sandbox snapshot delete [OPTIONS] SNAPSHOT_ID

Arguments

Name	Type	Required	Description
`SNAPSHOT_ID`	`text`	yes	Snapshot ID to delete.

Options

Option	Type	Required	Default	Description
`--api-key`	`TEXT`	no	`Sentinel.UNSET`	Sandbox API key.
`--yes`, `-y`	—	no	—	Delete without prompting for confirmation.

Examples

$ sandbox snapshot delete snap-42

Snapshot deleted

lightning sandbox snapshot get

Show a sandbox snapshot.

Usage:

lightning sandbox snapshot get [OPTIONS] SNAPSHOT_ID

Arguments

Name	Type	Required	Description
`SNAPSHOT_ID`	`text`	yes	Snapshot ID to inspect.

Options

Option	Type	Required	Default	Description
`--api-key`	`TEXT`	no	`Sentinel.UNSET`	Sandbox API key.
`--json`	—	no	`Sentinel.UNSET`	Print JSON output.

Examples

$ sandbox snapshot get snap-42
┏━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┳━━━━━━┓
┃ ID      ┃ Status ┃ Source sandbox ┃ Runtime ┃ Size     ┃ Auto ┃
┡━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━╇━━━━━━┩
│ snap-42 │ ready  │ devbox         │ python  │ 12.3 MiB │ no   │
└─────────┴────────┴────────────────┴─────────┴──────────┴──────┘

lightning sandbox snapshot list

List sandbox snapshots.

Usage:

lightning sandbox snapshot list [OPTIONS]

Options

Option	Type	Required	Default	Description
`--api-key`	`TEXT`	no	`Sentinel.UNSET`	Sandbox API key.
`--name`	`TEXT`	no	`Sentinel.UNSET`	Filter by source sandbox name.
`--page-token`	`TEXT`	no	`Sentinel.UNSET`	Pagination token returned by a previous list call.
`--limit`	`INTEGER`	no	`Sentinel.UNSET`	Maximum number of snapshots to return.
`--teamspace`	`TEXT`	no	`Sentinel.UNSET`	Only list snapshots in this teamspace (format: owner/teamspace).
`--sort-order`	`[asc\|desc]`	no	`Sentinel.UNSET`	Sort by creation time.
`--json`	—	no	`Sentinel.UNSET`	Print JSON output.

Examples

$ sandbox snapshot list --teamspace owner/teamspace --limit 2
┏━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┳━━━━━━┓
┃ ID      ┃ Status ┃ Source sandbox ┃ Runtime ┃ Size     ┃ Auto ┃
┡━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━╇━━━━━━┩
│ snap-42 │ ready  │ devbox         │ python  │ 12.3 MiB │ no   │
└─────────┴────────┴────────────────┴─────────┴──────────┴──────┘

$ sandbox snapshot list --teamspace owner/teamspace --json
{
  "snapshots": [
    {
      "id": "snap-42",
      "status": "ready"
    }
  ],
  "total_size": 1
}

lightning sandbox start

Start a stopped persistent sandbox.

Usage:

lightning sandbox start [OPTIONS] SANDBOX_ID

Arguments

Name	Type	Required	Description
`SANDBOX_ID`	`text`	yes	Sandbox ID to start.

Options

Option	Type	Required	Default	Description
`--api-key`	`TEXT`	no	`Sentinel.UNSET`	Sandbox API key.
`--json`	—	no	`Sentinel.UNSET`	Print JSON output.

Examples

$ sandbox start sbx-42

devbox

lightning sandbox stop

Stop a sandbox.

Persistent sandboxes may return an automatic snapshot that can be used for later resume or restore workflows.

Usage:

lightning sandbox stop [OPTIONS] SANDBOX_ID

Arguments

Name	Type	Required	Description
`SANDBOX_ID`	`text`	yes	Sandbox ID to stop.

Options

Option	Type	Required	Default	Description
`--api-key`	`TEXT`	no	`Sentinel.UNSET`	Sandbox API key.
`--json`	—	no	`Sentinel.UNSET`	Print JSON output.

Examples

$ sandbox stop sbx-42

Stopped sandbox sbx-42

Auto snapshot: snap-abc123

$ sandbox stop sbx-42 --json

{
  "auto_snapshot_id": "snap-abc123",
  "id": "sbx-42"
}

lightning sandbox update

Update a sandbox.

The backend update route currently supports resuming stopped persistent sandboxes. Use sandbox start as the shorter lifecycle command.

Usage:

lightning sandbox update [OPTIONS] SANDBOX_ID

Arguments

Name	Type	Required	Description
`SANDBOX_ID`	`text`	yes	Sandbox ID to update.

Options

Option	Type	Required	Default	Description
`--api-key`	`TEXT`	no	`Sentinel.UNSET`	Sandbox API key.
`--resume`	—	no	`Sentinel.UNSET`	Resume a stopped persistent sandbox.
`--json`	—	no	`Sentinel.UNSET`	Print JSON output.

Examples

$ sandbox update sbx-42 --resume

devbox

Was this page helpful?