Skip to main content
POST
Run a command against a sandbox snapshot
Starts a billable VM restored from the snapshot, runs command with sh -c under timeoutMs (1,000-300,000, default 60,000), releases the VM and answers exitCode, stdout and stderr (at most 262,144 characters each) and durationMs. Nothing the command does persists. A command the timeout stops answers timedOut: true with a null exitCode and empty output. The command is never echoed back. Before the VM starts, one audit event records who replayed it, the snapshot and the command (masked, at most 2,000 characters); if that record cannot be written, nothing runs.

Idempotency

The output may hold secrets, so it is never stored. With an Idempotency-Key, a repeat with the same key answers 409 idempotency_result_unavailable and never runs the command again; the same key with a different body is 422. While Forge is stopped, every replay is refused.

Masking

Runtime text is masked before it is cut to its cap: credential-shaped strings (JWTs, Bearer tokens, x-access-token: URLs and GitHub tokens) are replaced by a [REDACTED] marker. Masking is defense in depth, not a scrubber: a secret in a shape it does not recognise still crosses.

Authority

You need factories:manage at the snapshot run’s home (403 naming it otherwise), besides reading the run’s sandboxes, and the credential’s scopes must reach factories:manage. A Forge agent may hold factories:manage and replays as its grants say.

Visibility

A snapshot is reachable only when it is active and names the run that created it, and you can read that run’s sandboxes (factories:read at the run’s home and at every company it carries). Any other snapshot (unknown, deleted, failed, created outside a run such as a procedure image, or of a run out of reach) answers 404 “Snapshot not found”, and nothing is provisioned.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

Optional logical intent key. A same-key repeat within 24 hours never runs the command again; it answers 409 because the result is not stored.

Required string length: 1 - 255

Path Parameters

snapshotId
string
required

An active snapshot a run created (GET /api/v2/sandboxes/getLineage).

Required string length: 1 - 200

Body

application/json
command
string
required

Run as sh -c <command> in a fresh VM restored from the snapshot.

Required string length: 1 - 16384
timeoutMs
integer

How long the command may run. Default 60,000.

Required range: 1000 <= x <= 300000

Response

The replayed command's result

data
object
required
meta
object
required