One bounded command
POST /api/v1/sandbox/{id}/execute accepts argv or a supported string command,
working_dir, environment, stream, and a 1,000–600,000 millisecond timeout.
Use argv for literal arguments; strings deliberately invoke shell interpretation.
Idempotency-Key, exact body/path, sandbox, and returned execution_id.
Do not wrap SDK mutations in another generic retry loop. The candidate CLI removes those
outer retries while preserving original SDK request identity.
Interpret the result
HTTP success is not command success: 200 can retain an unknown outcome. Output truncation
is separate from observed exit; a missing exit or malformed output cannot become success.
Read the original receipt
Preserve event IDs as opaque cursors after consuming complete events. A replay reset replaces
accumulated output with the retained snapshot. Incomplete frames do not advance the cursor.
SDK receipt waits/reconnection observe the original command rather than submit a new one.
A terminal receipt can be
outcome_unknown. Local wait expiry/abort stops observation and
can leave the command running. Cancellation acknowledgement is not termination proof; inspect
the eventual receipt and relevant side effects. Agent/pod ownership fences prevent stale
handles from controlling another worker.
Supervised processes
Use/sandbox/{id}/processes for background workers. Start/get/list, result, logs, binary
stdin, signals, and deletion/termination are separate operations. Restart policy is explicit.
Enable stdin at start if later input is required, and preserve its exact base64 bytes.
GET /processes/{processId}/result returns outcome, nullable exit_code/signal, complete,
output-capture state, timestamps, and bounded streams. Outcomes include pending, succeeded,
failed, cancelled, timed_out, and unknown. complete verifies terminal process/log ends;
output can still be truncated and task quality remains separate.
Logs use returned next_offset; retain stream/process/sandbox identity and rotation flags.
The workbench validates binary output and bounded tails, preserving a stale prior observation
when refresh fails. It never turns observation into another worker launch.
Prepared tasks add private parent journals and exact
command/workspace/process identity. Registry discovery does not reconstruct every private
control or result receipt.
Source: Node execution/process handlers, SDK receipt APIs, and docs/EXECUTION_READINESS.md,
checked at 67bc2370 on October 20, 2026. Continue with
the quickstart or
the workbench.