Skip to main content

​
Common Errors

​
401 Unauthorized

Your API key is missing or invalid.
  • Check that OPENCOMPUTER_API_KEY is set: echo $OPENCOMPUTER_API_KEY
  • Verify the key in your code matches what’s in the dashboard
  • CLI users: run oc config show to check the stored key

​
Sandbox not found

The sandbox may have been killed or timed out (auto-hibernated or stopped). 
oc ls                     # list all sandboxes
oc sandbox get sb-abc123  # check a specific sandbox
In code: 
const running = await sandbox.isRunning();

​
Connection refused

The sandbox is still starting up, or it’s hibernated and hasn’t finished waking.
  • Check the sandbox status — if hibernated, call wake() or oc sandbox wake
  • If just created, wait a moment for the VM to boot (~150ms typical)

​
Timeout errors

Command timeout: Increase the timeout parameter on exec.run() or use --timeout with oc exec. Default is 60s for SDK exec.run(), unlimited for CLI without --wait. Idle timeout: Sandboxes auto-hibernate after 300s of inactivity. Increase with sandbox.setTimeout() or oc sandbox set-timeout. The timeout resets on every operation.

​
Agent exits immediately

  • Check that the sandbox has the Claude Agent SDK installed (the default template includes it)
  • Verify ANTHROPIC_API_KEY is available — pass it via envs on sandbox create if the agent needs it
  • Use the onError callback to capture stderr from the agent process

​
Debugging Tips

​
Check sandbox status

oc sandbox get sb-abc123

console.log(sandbox.status);
const running = await sandbox.isRunning();

​
List running processes

oc exec sb-abc123 --wait -- ps aux

const sessions = await sandbox.exec.list();
for (const s of sessions) {
  console.log(s.sessionID, s.running, s.command);
}

​
Capture agent errors

const session = await sandbox.agent.start({
  prompt: "...",
  onEvent: (event) => {
    if (event.type === "error") console.error("Agent error:", event.message);
  },
  onError: (data) => console.error("Stderr:", data),
});

​
Read sandbox logs

oc exec sb-abc123 --wait -- cat /var/log/syslog
oc exec sb-abc123 --wait -- journalctl --no-pager -n 50

​
Getting Help