Agent Sandbox Troubleshooting
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— notBearer. This is the most common single mistake, because the rest of the platform usesBearer.
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.
--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’stimeout_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.
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 tostateset-direct, which takes explicit commands with no interpretation layer: