> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ns.rocks/llms.txt
> Use this file to discover all available pages before exploring further.

# Debug Retained Machines

> Inspect retained agent, service, and failed workflow machines with PTY, SSH, commands, and files.

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

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
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:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace agent machine repo-review-agent --run adrun_123
```

## Inspect With CLI Commands

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
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:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
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:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace ssh mch_123
```

## Desktop Debugging

For GUI templates or browser-based tests, use the desktop viewer or desktop
automation:

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
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.

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine kill mch_123
```

## Related

* [Agent Deployments](../agents/deployments)
* [PTY sessions](./pty)
* [SSH access](./ssh)
* [Desktop environments](../desktop/overview)
* [Filesystem](../filesystem)