Skip to main content
Retained machines 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 machine ID: 
nullspace agent machine repo-review-agent --run adrun_123

​
Inspect With CLI Commands

nullspace machine exec mch_123 --shell "pwd && ls -la /workspace"
nullspace machine download mch_123 /workspace/result.json ./result.json
nullspace machine logs mch_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 machine pty create mch_123 --cols 120 --rows 30
nullspace machine pty connect mch_123 --session-id ses_123
Use SSH when your local tool expects OpenSSH: 
nullspace ssh mch_123

​
Desktop Debugging

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

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

​
Cleanup

Retained machines consume capacity until they expire or are destroyed. 
nullspace machine kill mch_123