Agent Templates

An agent template is a reusable package that defines what code an agent runs. Templates are referenced by name in workspace configurations — the same template can power multiple agent instances across different workspaces.

Template structure

Each template lives in its own directory with a dspatch.agent.yml configuration file:

The dspatch.agent.yml file declares the template's metadata, entry point, dependencies, and what resources it needs from the host environment.

Template sources

Templates can come from three places:

When a workspace starts, the container runtime clones or copies each template's source into the container and installs its dependencies.

Agent Template Configuration

Every agent template must contain a dspatch.agent.yml file at the root of its directory. This is the only accepted filename.

Directory structure

Only dspatch.agent.yml is required. All other files are optional and depend on your agent's needs.

Field reference

Full example

name: Code Reviewer
description: Reviews pull requests for correctness and style.
entry_point: reviewer.py
readme: README.md
pre_install: ./scripts/pre_install.sh
post_install: ./scripts/post_install.sh
fields:
  system_prompt: WW91IGFyZSBhIGNvZGUgcmV2aWV3ZXIu
  authority: UmV2aWV3IGFuZCBzdWdnZXN0IGNoYW5nZXMu
required_env:
  - ANTHROPIC_API_KEY
required_mounts:
  - /root/.claude/.credentials.json

Dependency installation

d:spatch automatically installs dependencies based on the files present in the template directory. The resolution order is:

1. pyproject.toml — installed with uv sync --no-dev
2. requirements.txt — installed with pip install -r requirements.txt
3. package.json — installed with the detected package manager (npm, pnpm, or yarn)

If pre_install or post_install scripts are defined, they run before and after the dependency installation step respectively.

Validation

When a workspace starts, d:spatch validates that:

• Every required_env key is present in the workspace or agent-level env map.
• Every required_mounts path is satisfied by a mount in the workspace configuration.

If validation fails, the workspace will not start and an error is reported.

Environment Variables

Environment variables are resolved in three layers at container startup. Later layers override earlier ones.

System variables

These are set automatically by d:spatch on every agent container.

Required environment variables

Only keys listed in your template's required_env are forwarded from the host to the container. Access them with os.environ as usual.

required_env:
  - OPENAI_API_KEY
  - CUSTOM_SERVICE_TOKEN

Workspace config example

env:
  LOG_LEVEL: debug
  SHARED_TOKEN: "abc123"

agents:
  coder:
    template: my-agent
    env:
      LOG_LEVEL: info  # overrides workspace-level
  reviewer:
    template: my-agent
    # inherits LOG_LEVEL=debug and SHARED_TOKEN from workspace

Template Fields

Use fields in dspatch.agent.yml to embed configuration that gets base64-encoded into environment variables at startup.

fields:
  - name: system_prompt
    label: System Prompt
    type: textarea
    default: "You are a helpful coding assistant."
  - name: authority
    label: Authority
    type: textarea
    default: "You may refactor code and fix bugs. Escalate API changes."

Two field names are well-known and automatically decoded by the SDK:

Manual encoding

Field values are base64-encoded. To encode a value manually:

echo -n "Your prompt here." | base64

The SDK decodes DSPATCH_FIELD_* variables automatically when referenced through ctx.setup() defaults.