Claude Agent SDK

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

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:

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

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.

Overview

Agent workspaces

Framework integrations

Local agent tooling

Deploy As A Job

Debugging

State Boundary

​Deploy As A Job

​Debugging

​State Boundary

​Related

Deploy As A Job

Debugging

State Boundary

Related