Skip to main content
Retained sandboxes let you inspect state after a job, service, or workflow failure. They are useful for debugging generated files, dependency installs, agent traces, server logs, and interactive prompts.

​
Retain A Failed Agent Run

nullspace agent run repo-review-agent \
  --retain-on-failure \
  --retention-seconds 3600 \
  --input-json '{"repo":"https://github.com/acme/repo"}'
Get the backing sandbox ID: 
nullspace agent sandbox repo-review-agent --run adrun_123

​
Inspect With CLI Commands

nullspace sandbox exec sb_123 --shell "pwd && ls -la /workspace"
nullspace sandbox download sb_123 /workspace/result.json ./result.json
nullspace sandbox logs sb_123
Use the Files API or CLI file commands for artifacts that should be copied out before cleanup.

​
Attach A Terminal

PTY access works without SSH tooling: 
nullspace sandbox pty create sb_123 --cols 120 --rows 30
nullspace sandbox pty connect sb_123 --session-id ses_123
Use SSH when your local tool expects OpenSSH: 
nullspace ssh sb_123

​
Desktop Debugging

For GUI templates or browser-based tests, use the desktop viewer or desktop automation: 
viewer = sandbox.desktop.viewer()
print(viewer.url)

image = sandbox.desktop.screenshot()
image.save("debug.png")

​
Cleanup

Retained sandboxes consume capacity until they expire or are destroyed. 
nullspace sandbox kill sb_123