Debug Retained Machines

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

Get started

Machines

Commands

Filesystem

Code Interpreter

Desktop

Templates

Volumes

Networking

Interactive access

Observability

Debug Retained Machines

Retain A Failed Agent Run

Inspect With CLI Commands

Attach A Terminal

Desktop Debugging

Cleanup

​Retain A Failed Agent Run

​Inspect With CLI Commands

​Attach A Terminal

​Desktop Debugging

​Cleanup

​Related

Retain A Failed Agent Run

Inspect With CLI Commands

Attach A Terminal

Desktop Debugging

Cleanup

Related