Sandbox failures usually look alike from the outside — the run ends without the outcome you wanted.
This is how to tell which one you hit.
Start with the output
Most misdiagnosis comes from not having the output. Stream it before anything else:
--verbose adds telemetry; --json makes the result parseable rather than prose.
Authentication
Symptom: 401 or 403 on any call.
- Confirm the key is valid and unexpired.
- Check the header format:
Authorization: ApiKey YOUR_API_KEY — not Bearer. This is the
most common single mistake, because the rest of the platform uses Bearer.
The CLI isn’t there
Symptom: command not found: stateset.
The sandbox image must include the CLI. If you’re on a custom or older image, rebuild it or update
the runtime image.
The write didn’t happen
Symptom: the run reports success, but nothing changed.
This is almost always a missing --apply. The CLI is read-only by default, so a write phrased
without the flag describes what would happen and exits cleanly. A clean exit with no effect is the
signature.
If --apply is present and the write still didn’t land, check guardrail policy for restricted
operations, and whether the action exceeded a
High-Value Action threshold and is awaiting
approval rather than having failed.
Timeouts
Symptom: the run ends abruptly at a consistent duration.
That consistency is the tell — it’s timeout_seconds, not the workload.
- Raise the timeout, or reduce the work.
- Prefer splitting the workflow: a run that dies takes one chunk with it rather than the whole job.
A hung agent bills for the full timeout. Raising it to make a symptom go away can turn a failing
run into an expensive one — check whether the agent is stuck in a loop first. See
Sandbox costs. Unexpected results, not errors
Symptom: the command succeeds and does the wrong thing.
If you’re using the natural-language binary, the phrasing was interpreted differently than you
meant. Switch to stateset-direct, which takes explicit commands with no interpretation layer:
For anything an agent runs unattended, this should be the default rather than the fallback.
Quick triage
Last modified on August 31, 2026
