> ## 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.

# Claude Agent SDK

> Deploy a Claude Agent SDK project as a managed Nullspace job.

Use this guide when your own Claude Agent SDK application should run inside
Nullspace as a repeatable Agent Deployment. If you want the Claude Code CLI
inside a machine workspace, use [Claude Code](./claude-code) instead.

Claude Agent SDK apps usually fit `mode = "job"`: receive input, run the agent,
write output files, and exit. Use a `service` only when your app exposes an HTTP
API around Claude.

## Deploy As A Job

```toml theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
name = "claude-agent-sdk-job"
mode = "job"
template = "base"
workdir = "/workspace/project"
install = "python -m pip install -e ."
entrypoint = "python main.py"

[env]
required = ["ANTHROPIC_API_KEY"]

[outputs]
paths = ["result.json", "reports"]
```

Deploy and run:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace agent deploy .
nullspace agent run claude-agent-sdk-job \
  --input-json '{"prompt":"write a short release note"}' \
  --env ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  --retain-on-failure \
  --json

nullspace agent logs claude-agent-sdk-job --run adrun_123
nullspace agent outputs claude-agent-sdk-job --run adrun_123
nullspace agent machine claude-agent-sdk-job --run adrun_123
```

See the [Claude Agent SDK job example](../examples/agent-deployment-claude-agent-sdk)
for a complete project.

## Debugging

Every run has a backing machine. Use `--retain-on-failure` when a failed Claude
run should leave a retained machine for PTY, SSH, command, file, or desktop
inspection.

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace agent shell claude-agent-sdk-job \
  --run adrun_123 \
  --cmd "ls -la && find reports -maxdepth 2 -type f"
```

## State Boundary

Nullspace owns deployment runs, logs, outputs, and backing machines. Claude
Agent SDK conversation state remains owned by your app. Keep session files in a
volume or app-managed storage when they must survive machine cleanup, and pass
your own conversation ID through the job input instead of treating a Nullspace
run ID as a Claude session ID.

## Related

* [Agent Primitives](./primitives)
* [Agent Deployments](./deployments)
* [Claude Code](./claude-code)
* [Volumes](../volumes/overview)