pome sandbox

pome sandbox manages hosted sandboxes on the Pome control plane—the same ones you see on the dashboard Twins page. It requires pome login (or POME_API_KEY).

pome session is the same command. session is the legacy name for a sandbox and stays a permanent alias, as do /v1/sessions, the ses_ id prefix and session_id in the wire format. Every example below works under either spelling. See Terminology.

GitHub and Stripe are supported today. Slack is local pome run only.

Usage

pome sandbox create [options]
pome sandbox list [options]
pome sandbox stop <session-id> [options]
pome sandbox kill <session-id>   # alias for stop

`sandbox create`

Spin up a hosted sandbox for a twin and print connection details.

Options

Flag	Default	Description
`--twin <name>`	—	Required. `github` or `stripe`.
`--api-url <url>`	`POME_API_URL` or `https://api.pome.sh`	Control-plane base URL.
`--show-secrets`	off	Print bearer tokens and API keys. Unsafe on shared terminals.
`--format <fmt>`	`text`	Output format: `text`, `json`, or `env` (shell `export` lines).

Examples

pome sandbox create --twin github
pome sandbox create --twin stripe --format env
pome sandbox create --twin github --show-secrets --format json

With --format env, output includes lines like:

export POME_GITHUB_REST_URL=...
export POME_AUTH_TOKEN=...
export POME_STRIPE_API_KEY=...    # stripe sandboxes only

`sandbox list`

List hosted sandboxes. Defaults to --state running, matching the dashboard view.

Options

Flag	Default	Description
`--state <state>`	`running`	Filter: `running`, `ready`, `done`, `expired`, or `all`. `running` matches both server-side `ready` and `running`.
`--limit <n>`	`20`	Maximum rows to return.
`--format <fmt>`	`text`	`text` or `json`.
`--api-url <url>`	`POME_API_URL` or `https://api.pome.sh`	Control-plane base URL.

Examples

pome sandbox list
pome sandbox list --state all --limit 50
pome sandbox list --format json

`sandbox stop`

Stop a hosted sandbox by id (ses_…). Pome creates the run row at finalize, so a still-open sandbox’s run has not been graded yet — stopping it without confirming would silently discard that run. An unconfirmed stop of an open sandbox is refused, naming the task, how long it’s been open, and telling you to pass --discard to confirm.

Arguments

Argument	Required	Description
`<session-id>`	Yes	Sandbox id from `sandbox create` or `sandbox list`.

Options

Flag	Default	Description
`--api-url <url>`	`POME_API_URL` or `https://api.pome.sh`	Control-plane base URL.
`--discard`	off	Confirm you mean to destroy a sandbox whose run has not been graded.

Examples

pome sandbox stop ses_abc123
pome sandbox kill ses_abc123   # same as stop

A stop on a still-open sandbox is refused rather than run:

Refused to stop ses_abc123: it is still open (running), so its run has not
been graded — Pome creates the run row at finalize, and stopping now
discards it.
  Task: my-task
  Open for 42s.
  To keep the run, finalize it instead. To discard it anyway:
  pome sandbox stop ses_abc123 --discard

To keep the run, finalize the sandbox instead (via the MCP finalize_run tool, or whatever finalized the run in your flow) — finalizing grades the run and flips the sandbox to done, so no sandbox stop is needed after. To discard the run anyway, re-run with --discard:

pome sandbox stop ses_abc123 --discard

Start

Guides

Examples

CLI

MCP

pome sandbox

Usage

`sandbox create`

Options

Examples

`sandbox list`

Options

Examples

`sandbox stop`

Arguments

Options

Examples

​Usage

​sandbox create

​Options

​Examples

​sandbox list

​Options

​Examples

​sandbox stop

​Arguments

​Options

​Examples

Usage

`sandbox create`

Options

Examples

`sandbox list`

Options

Examples

`sandbox stop`

Arguments

Options

Examples