Your First Agent & Workspace
Get an agent template and create a workspace to run it in d:spatch.
Agent Templates
An agent template defines what code runs inside each agent's process. d:spatch ships with built-in templates (like claude-code), but you can also browse community templates on the Hub or create your own.
Get an agent from the Hub
The fastest way to get started is to clone a template directly from the app or CLI:
dspatch provider add https://github.com/dspatch/agent.claude-codeThis registers the git repository as an agent provider. You can browse available templates in the Hub tab of the d:spatch app, or add any template directly from a git URL.
Create your own agent
A minimal agent template looks like this:
The dspatch.agent.yml file describes your agent template:
name: My Custom Agent
description: A simple agent that responds to prompts.
entry_point: agent.py
required_env:
- ANTHROPIC_API_KEY| Field | Description |
|---|---|
name | Display name for the template. |
description | Short description shown in the UI. |
entry_point | The Python file to run when the agent starts. |
required_env | Environment variables that must be set before the agent can launch. |
Here is a minimal agent using ClaudeAgentContext:
from claude_agent_sdk import ClaudeAgentOptions
from dspatch import ClaudeAgentContext, DspatchEngine
dspatch = DspatchEngine()
@dspatch.agent(ClaudeAgentContext)
async def my_agent(prompt: str, ctx: ClaudeAgentContext):
ctx.setup(
system_prompt="You are a helpful coding assistant.",
options=ClaudeAgentOptions(
model="claude-sonnet-4-5-20250929",
max_turns=200,
),
)
async with ctx:
while True:
try:
await ctx.run(prompt)
except Exception as e:
ctx.log(f"Error: {e}", level="error")
prompt = yield
if prompt is None:
break
dspatch.run()DspatchEngineconnects your agent to the d:spatch platform.@dspatch.agent(ClaudeAgentContext)registers your function using the Claude agent context.ctx.setup()configures the system prompt and model options.yieldpauses the agent and waits for the next message (generator pattern for multi-turn).
For the full API reference, see the Agent SDK documentation. For details on template configuration, see Agent Templates.
Workspaces
A workspace is the environment where agents run, communicate, and collaborate. Each workspace maps to a single Docker container and is defined by a dspatch.workspace.yml file.
Get a workspace from the Hub
You can clone pre-configured workspaces from the Hub:
dspatch hub clone-workspace coding-teamThis downloads the workspace config and any referenced agent templates. Browse available workspaces in the Hub tab of the d:spatch app.
Create your own workspace
A minimal workspace with one agent:
name: my-first-workspace
env:
ANTHROPIC_API_KEY: your-key-here
agents:
assistant:
template: claude-code
env: {}
sub_agents: {}
peers: []
auto_start: true
workspace_dir: /path/to/your/project
mounts:
- host_path: ~/.claude/.credentials.json
container_path: /root/.claude/.credentials.json
read_only: true
docker:
network_mode: host
ports: []
gpu: false
home_persistence: trueWorkspaces support hierarchical agent topologies. Here, a lead agent supervises two sub-agents:
name: coding-team
agents:
lead:
template: claude-code
auto_start: true
sub_agents:
coder:
template: claude-code
auto_start: false
tester:
template: claude-code
auto_start: false
peers: []The lead starts automatically. The coder and tester remain idle until the lead delegates work to them.
Workspace field reference
| Field | Description |
|---|---|
name | A human-readable name for the workspace. |
env | Environment variables available to all agents in the workspace. |
agents | A map of agent instance names to their configurations. |
workspace_dir | The host directory mounted into the container as the working directory. |
mounts | Additional files or directories to mount into the container. |
docker | Docker-level settings: network mode, port mappings, GPU access, and home directory persistence. |
Workspace directory mounting
The workspace_dir path on your host machine is mounted as /workspace inside the container. Agents read and write files relative to this path.
For the full workspace configuration reference, see Workspaces. For more on agent hierarchies, see Hierarchies.