Agents

When a pylon job fires, Pylon spins up a fresh Docker container for the configured agent, mounts the workspace, injects the prompt, and lets the agent work. Each job gets its own isolated container — the agent has no access to previous jobs or the host filesystem beyond the mounted workspace. Pylon currently supports two agents: Claude Code and OpenCode. You configure an agent under the agent key in pylon.yaml. If you omit the agent block, Pylon falls back to the global defaults in ~/.pylon/config.yaml.

Agent fields

Field	Required	Description
`type`	No	Agent to use: `claude` or `opencode`. Defaults to global setting, or `claude` if not set.
`auth`	No	Authentication method. See per-agent options below.
`api_key`	No	API key reference, e.g. `${ANTHROPIC_API_KEY}`. Used when `auth` is `api_key` or `api-key`.
`provider`	No	LLM provider for OpenCode: `anthropic`, `openai`, or `google`.
`env`	No	Additional environment variables to inject into the container.
`prompt`	Yes	The instruction sent to the agent. Supports `{{ .body.field }}` templating.
`timeout`	No	Maximum time the agent container can run, e.g. `10m`, `30m`. Defaults to `15m`.
`volumes`	No	Host directories to mount into the container, e.g. credential directories. See pylon.yaml.

Claude Code

Claude Code (type: claude) is Anthropic’s agentic coding tool. It supports two auth methods:

OAuth (recommended)
API key

With OAuth auth, Pylon mounts your local ~/.claude/ directory into the container so Claude Code reuses your existing session. No API key is needed.

agent:
  type: claude
  auth: oauth
  prompt: |
    Investigate this Sentry error and suggest a fix.
    Title: {{ .body.data.event.title }}
    Culprit: {{ .body.data.event.culprit }}
  timeout: 10m

OAuth auth requires that you have already authenticated Claude Code on the host machine by running claude at least once.

With API key auth, Pylon passes your Anthropic API key to the container as ANTHROPIC_API_KEY.

agent:
  type: claude
  auth: api_key
  api_key: "${ANTHROPIC_API_KEY}"
  prompt: |
    Review this pull request for bugs and security issues.
  timeout: 15m

Store the key in ~/.pylon/.env:

ANTHROPIC_API_KEY=sk-ant-...

OpenCode

OpenCode (type: opencode) is a multi-provider coding agent with a built-in free tier (Zen) that requires no API key.

Zen (no key needed)
API key (bring your own)

OpenCode’s Zen mode uses a built-in model — no API key or provider setting required.

agent:
  type: opencode
  auth: none
  prompt: |
    Audit this codebase for outdated dependencies and code quality issues.
  timeout: 30m

To use your own provider with OpenCode, set auth to api-key, specify a provider, and supply the key.

agent:
  type: opencode
  auth: api-key
  provider: anthropic
  api_key: "${ANTHROPIC_API_KEY}"
  prompt: |
    Review this PR and suggest improvements.
  timeout: 15m

Supported providers: anthropic, openai, google.

Prompt templating

The prompt field supports Go template syntax. Use {{ .body.field }} to inject values from the webhook payload into the prompt at runtime.

agent:
  prompt: |
    Investigate this Sentry error and suggest a fix.

    Title: {{ .body.data.event.title }}
    Culprit: {{ .body.data.event.culprit }}
    Level: {{ .body.data.event.level }}
    Platform: {{ .body.data.event.platform }}
    Sentry URL: {{ .body.data.event.web_url }}

For GitHub webhooks, you can reference fields like {{ .body.pull_request.title }}, {{ .body.pull_request.head.ref }}, or {{ .body.repository.clone_url }}.

Use pylon test <name> to send a sample payload and preview how the prompt renders before relying on it in production.

Timeout

The timeout field sets the maximum time the agent container is allowed to run. If the agent exceeds this limit, Pylon stops the container and records the job as timed out.

Default: 15m
Format: Go duration string — 10m, 30m, 1h, etc.

agent:
  timeout: 10m

You can also set a global default timeout in ~/.pylon/config.yaml under docker.default_timeout. The per-pylon timeout takes priority.

Additional environment variables

Use env to inject arbitrary environment variables into the agent container:

agent:
  type: claude
  auth: oauth
  env:
    NODE_ENV: production
    DATABASE_URL: "${DATABASE_URL}"
  prompt: "Run the test suite and report failures."
  timeout: 20m

Coming soon

The following agents are planned but not yet available:

Codex (OpenAI)
Aider

Get Started

Concepts

YAML

Examples

Running

Agent fields

Claude Code

OpenCode

Prompt templating

Timeout

Additional environment variables

Coming soon

​Agent fields

​Claude Code

​OpenCode

​Prompt templating

​Timeout

​Additional environment variables

​Coming soon

Agent fields

Claude Code

OpenCode

Prompt templating

Timeout

Additional environment variables

Coming soon