Synopsis
Description
pome sandbox manages hosted sandboxes on the Pome control plane — the same ones
the dashboard Twins page shows. Every subcommand needs credentials, from
pome login or POME_API_KEY.
Reach for it when you want a twin to hold state while you work against it by
hand, or from a harness that is not pome run. pome run creates and
tears down its own sandbox; you do not need this command for an ordinary run.
All five twins are available: github, stripe, slack, gmail, and linear —
115 MCP tools and 263 REST and GraphQL surfaces between them, each one’s coverage
broken out on its own page.
Repeat --twin to stand up several in one sandbox. They share the sandbox’s
id, bearer token, lifetime, and bill — but each twin keeps its own state, and
a fact crosses from one twin to another only if your agent carries it.
A sandbox holds at most three twins. The cloud provisions one isolated
sandbox per twin, so a fourth --twin is refused with a 422 and
too_many_twins rather than dropped quietly. Split the work across two sandboxes
if you need more.
sandbox create
Start a hosted sandbox and print its connection details.
Options
Plus the global flags —
--api-url, --artifacts-dir, and -V, --version.
Examples
Start one twin:--twin off stops the command rather than
guessing.
Secrets
Connection details go to the terminal; secrets never do.--secrets-file is
the only way to get them out. The file it writes looks like this:
POME_AUTH_TOKEN is the bearer for every call to the twin. Each twin in the
sandbox adds its own POME_<TWIN>_REST_URL and POME_<TWIN>_MCP_URL pair,
plus its provider-shaped variables (POME_SLACK_TOKEN, POME_GMAIL_TOKEN,
POME_STRIPE_API_KEY and POME_STRIPE_API_BASE) — those are what the twin
serves inside the sandbox, not credentials for reaching it. Add the file to
.gitignore.
sandbox list
List your hosted sandboxes. Defaults to --state running, which is the
dashboard’s view.
Options
Plus the global flags —
--api-url, --artifacts-dir, and -V, --version.
Examples
sandbox stop
Stop a hosted sandbox by id.
Pome creates the run row at finalize, so a sandbox that is still open holds a run
nobody has graded. Stopping it discards that run. An unconfirmed stop of an open
sandbox is refused, naming the task and how long the sandbox has been open.
Arguments
Options
Plus the global flags —
--api-url, --artifacts-dir, and -V, --version.
Examples
Stop a sandbox whose run is already graded:finalize_run
tool, or whatever finalizes runs in your flow. Finalizing grades the run and
flips the sandbox to done, so no sandbox stop is needed afterwards. To
discard the run anyway, pass --discard:
Exit status
See the canonical table. A refused stop exits5, the
usage-error code, and leaves the sandbox running.