pylon.yaml - Pylon

Each pylon you create gets its own config file at ~/.pylon/pylons/<name>/pylon.yaml. Running pylon construct <name> creates this file through an interactive prompt; you can open it in your editor at any time with pylon edit <name>. Per-pylon settings take priority over the global defaults in ~/.pylon/config.yaml, so you only need to specify fields that differ from the global configuration.

Examples

These are complete, copy-pasteable pylon.yaml files covering the three most common patterns.

Sentry webhook with approval

A webhook pylon that triages Sentry errors. HMAC validation ensures only authentic Sentry payloads are accepted, and approval: true requires a human to approve each job before the agent starts.

# ~/.pylon/pylons/sentry-triage/pylon.yaml

# Identifier for this pylon. Matches the directory name.
name: sentry-triage

# Shown in `pylon list` output.
description: "Sentry error triage for the nexus project"

# Set to true to pause this pylon without deleting it.
disabled: false

# Set by `pylon construct`. Do not edit.
created: 2025-06-01T09:00:00Z

trigger:
  type: webhook
  # Incoming POST requests to this path activate the pylon.
  path: /sentry-triage
  # HMAC secret for signature validation. References ~/.pylon/.env.
  secret: "${SENTRY_WEBHOOK_SECRET}"
  # Header where Sentry places its HMAC signature.
  signature_header: "X-Sentry-Hook-Signature"

workspace:
  type: git-clone
  repo: "git@github.com:myorg/nexus.git"
  ref: main

channel:
  type: telegram
  telegram:
    bot_token: "${TELEGRAM_BOT_TOKEN}"
    chat_id: -1001234567890
    allowed_users:
      - 987654321
  # Topic and message use template variables to show Sentry event info.
  topic: "{{ .body.data.event.title }}"
  message: |
    {{ .body.data.event.title }}
    {{ .body.data.event.culprit }}
    {{ .body.data.event.web_url }}
  # Human must click Approve before the agent starts.
  approval: true

agent:
  type: claude
  auth: oauth
  # Template variables inject live Sentry payload data into the prompt.
  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 }}
  timeout: "10m"

GitHub PR review (no approval)

A webhook pylon that reviews every pull request automatically. The workspace repo and branch are resolved dynamically from the GitHub webhook payload, so the agent always clones the exact branch under review. No approval step — the agent starts immediately.

# ~/.pylon/pylons/pr-review/pylon.yaml

name: pr-review
description: "Automated code review for pull requests"
disabled: false
created: 2025-07-15T14:30:00Z

trigger:
  type: webhook
  path: /pr-review
  # GitHub sends signatures in this header when a webhook secret is set.
  secret: "${GITHUB_WEBHOOK_SECRET}"
  signature_header: "X-Hub-Signature-256"

workspace:
  type: git-clone
  # Dynamic repo/ref from the webhook payload -- Pylon clones the PR branch.
  repo: "{{ .body.repository.clone_url }}"
  ref: "{{ .body.pull_request.head.ref }}"

channel:
  type: telegram
  telegram:
    bot_token: "${TELEGRAM_BOT_TOKEN}"
    chat_id: -1001234567890
    allowed_users:
      - 987654321
  topic: "PR #{{ .body.number }}: {{ .body.pull_request.title }}"
  message: |
    New PR from {{ .body.pull_request.user.login }}
    {{ .body.pull_request.html_url }}
  # No approval required -- agent starts on every PR event.
  approval: false

agent:
  type: claude
  auth: api_key
  api_key: "${ANTHROPIC_API_KEY}"
  prompt: |
    Review pull request #{{ .body.number }}: {{ .body.pull_request.title }}.
    Check for bugs, security issues, and suggest improvements.
    Focus on the diff -- do not rewrite files unless there is a clear defect.
  timeout: "15m"

Cron audit (scheduled weekly)

A cron pylon that runs a weekly security audit. There is no webhook trigger — Pylon fires the job on a schedule. The workspace is a fresh git clone so the agent always audits the latest code.

# ~/.pylon/pylons/weekly-audit/pylon.yaml

name: weekly-audit
description: "Weekly security audit of the platform repo"
disabled: false
created: 2025-08-01T08:00:00Z

trigger:
  # Cron trigger instead of webhook.
  type: cron
  # Every Monday at 9 AM.
  cron: "0 9 * * 1"

workspace:
  type: git-clone
  repo: "git@github.com:myorg/platform.git"
  ref: main

channel:
  type: slack
  slack:
    bot_token: "${SLACK_BOT_TOKEN}"
    app_token: "${SLACK_APP_TOKEN}"
    channel_id: "C0123456789"
    allowed_users:
      - "U0123456789"
  topic: "Weekly security audit"
  message: "Scheduled security audit starting now."
  # No approval -- cron jobs run unattended.
  approval: false

agent:
  type: claude
  auth: api_key
  api_key: "${ANTHROPIC_API_KEY}"
  env:
    AUDIT_SCOPE: "full"
  prompt: |
    Run a security audit of this codebase. Check for:
    - Hardcoded secrets or credentials
    - SQL injection or command injection risks
    - Outdated dependencies with known CVEs
    - Overly permissive file or network access

    Write a summary of findings to AUDIT.md in the repo root.
  timeout: "30m"

Field reference

Top-level fields

name

string

required

Identifier for this pylon. Must match the directory name under ~/.pylon/pylons/. Set automatically by pylon construct.

description

string

Optional human-readable description shown in pylon list output.

disabled

boolean

default:"false"

When true, pylon start skips this pylon entirely. Use this to temporarily pause a pylon without deleting it.

created

string

ISO 8601 timestamp set automatically when you run pylon construct. Do not edit this field.

`trigger`

trigger.type

string

required

How the pylon is activated. Accepted values: webhook, cron.

trigger.path

string

URL path for the webhook endpoint (for example, /my-pipeline). Required when type is webhook. Pylon registers this path on the global server port when the daemon starts.

trigger.cron

string

Cron expression for scheduled pylons (for example, 0 9 * * 1-5 for weekdays at 9 AM). Required when type is cron.

trigger.secret

string

HMAC secret used to validate incoming webhook signatures. When set, Pylon rejects requests whose signature does not match. Use ${VAR} to reference a value from ~/.pylon/.env.

trigger.signature_header

string

HTTP header Pylon reads to find the HMAC signature (for example, X-Hub-Signature-256). Required when trigger.secret is set.

trigger.public_url

string

Overrides server.public_url from the global config for this pylon only. Useful when a single Pylon server serves webhooks from multiple domains.

`workspace`

workspace.type

string

required

How the agent accesses source code. Accepted values:

git-clone — Pylon clones the repository fresh for each job.
git-worktree — Pylon creates a worktree from a local clone, which is faster than a full clone.
local — Pylon mounts a local directory from the host into the container.
none — No codebase. Use this for pylons that do not need to read or modify files.

workspace.repo

string

Git repository URL. Use SSH (git@github.com:org/repo.git) for private repositories. Supports template variables so you can resolve the URL from the webhook payload (for example, {{ .body.repository.clone_url }}). Required when type is git-clone or git-worktree.

workspace.ref

string

Branch or tag to check out. Supports template variables (for example, {{ .body.pull_request.head.ref }}). Defaults to main when not specified.

workspace.path

string

Absolute path to a local directory on the host. Pylon mounts this directory into the agent container. Required when type is local.

`channel`

The channel block is optional. When omitted, the pylon uses the global defaults.channel from config.yaml. When present, the pylon-level settings take full priority.

channel.type

string

Notification backend for this pylon. Accepted values: telegram, slack, webhook, stdout. Overrides the global default.

channel.telegram

TelegramConfig

Telegram connection settings. Accepts the same fields as defaults.channel.telegram in the global config. Required when channel.type is telegram.

channel.slack

SlackConfig

Slack connection settings. Accepts the same fields as defaults.channel.slack in the global config. Required when channel.type is slack.

channel.topic

string

Thread or topic subject line shown in the notification. Supports template variables for injecting webhook payload data.

channel.message

string

Notification message body displayed above the Approve/Ignore buttons. Supports template variables.

channel.approval

boolean

default:"false"

When true, Pylon sends a notification with Approve and Ignore buttons and waits for a human to respond before starting the agent. When false, the agent starts immediately on every trigger event.

`agent`

The agent block is optional. When omitted, the pylon uses defaults.agent from the global config.

agent.type

string

Agent runtime for this pylon. Accepted values: claude, opencode. Overrides the global default.

agent.auth

string

Authentication method. Overrides the global default for the chosen agent type. Accepted values: oauth, api_key (Claude); none, api-key (OpenCode).

agent.api_key

string

API key reference, used when auth is api_key. Use ${VAR} to reference a value from ~/.pylon/.env (for example, ${ANTHROPIC_API_KEY}). This lets you assign a different key per pylon.

agent.provider

string

LLM provider for OpenCode agents. Accepted values: anthropic, openai, google. Overrides the global default.

agent.env

map[string]string

Additional environment variables injected into the agent container. Use this to pass service-specific configuration without hardcoding values in the prompt.

agent.prompt

string

required

The instruction sent to the agent when a job starts. Supports Go template syntax to inject data from the webhook payload. See the Prompt templates section below.

agent.timeout

string

Maximum run time for a single job (for example, 10m, 30m). Overrides docker.default_timeout from the global config.

agent.volumes

string[]

Host directories to mount into the agent container. Each entry uses the format source:target[:ro|rw]. Defaults to read-only (ro) when the mode is omitted. See the Volumes section below.

Prompt templates

Pylon renders your agent prompt as a Go template before sending it to the agent container. This means you can embed data from the incoming webhook payload directly in the prompt, so the agent receives context-rich instructions without any extra glue code. The same template syntax works in channel.topic and channel.message, letting you surface the right information in your notification thread title and preview message.

Template syntax

Access a field from the webhook JSON body using double curly braces and the .body prefix:

{{ .body.<field> }}

Nested fields follow the same dot notation as the JSON structure:

{{ .body.pull_request.head.ref }}

Pylon uses the standard Go text/template package. Any valid Go template expression works, including conditionals and range loops, but most prompts only need simple field substitutions.

Available variables

Variable	Description
`{{ .body.error }}`	Generic top-level error message
`{{ .body.issue.title }}`	Issue title (GitHub, Linear, or generic)
`{{ .body.number }}`	Pull request or issue number
`{{ .body.pull_request.title }}`	GitHub pull request title
`{{ .body.pull_request.head.ref }}`	Branch name for a pull request
`{{ .body.repository.clone_url }}`	HTTPS clone URL for the repository
`{{ .body.data.event.title }}`	Sentry event title
`{{ .body.data.event.culprit }}`	Sentry culprit file and function
`{{ .body.data.event.level }}`	Sentry severity level (e.g. `error`, `fatal`)
`{{ .body.data.event.platform }}`	Sentry platform (e.g. `python`, `javascript`)
`{{ .body.data.event.web_url }}`	Link to the Sentry issue in the web UI

Any field present in the POST body is accessible. The table above lists common examples — your actual available fields depend on the service sending the webhook.

Template examples

Sentry error triage — inject event details from a Sentry webhook:

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

GitHub pull request review — resolve the repo and branch from the payload:

workspace:
  type: git-clone
  repo: "{{ .body.repository.clone_url }}"
  ref: "{{ .body.pull_request.head.ref }}"

agent:
  prompt: |
    Review pull request #{{ .body.number }}: {{ .body.pull_request.title }}.
    Check for bugs, security issues, and suggest improvements.

Notice that template variables also work in workspace.repo and workspace.ref, so Pylon clones the exact branch being reviewed. Notification channel fields — template variables apply to channel.topic and channel.message too, not just the agent prompt:

channel:
  approval: true
  topic: "{{ .body.data.event.title }}"
  message: |
    {{ .body.data.event.title }}
    {{ .body.data.event.culprit }}
    {{ .body.data.event.web_url }}

Testing template expansion

Use pylon test with a --payload flag to see how your templates expand against a sample payload before sending real traffic:

pylon test my-pylon --payload '{"error": "divide by zero", "issue": {"title": "ZeroDivisionError"}}'

Pylon prints the resolved prompt and channel message so you can confirm the substitution looks correct. For more complex payloads, pass a path to a JSON file:

pylon test my-pylon --payload "$(cat sample-sentry-event.json)"

Building `channel.message` interactively

Writing message templates by hand means guessing at payload field names. Nexus ships an interactive builder that reads the last real trigger payload for a pylon, shows you its structure, and writes a channel.message block directly into pylon.yaml when you save.

Trigger the pylon at least once

Send a real webhook or run pylon test <name> so Pylon has a sample payload to read from. The builder refuses to open if the pylon has never fired.

Open Nexus and select the pylon

Run pylon nexus, highlight the pylon in the sidebar, and press l or enter to focus the detail panel.

Press `a` to open the builder

Nexus renders the payload as collapsible groups. Navigate with j/k, expand groups with space, and check fields you want in the message with space.

Save and close

Press enter to save. Nexus writes labelled Go template expressions into channel.message. For example, checking a title field under event produces:

channel:
  message: |
    Title: {{ .body.event.title }}

Press esc to cancel without saving.

See Nexus message template builder for the full keybinding reference.

Tips

If a referenced field is missing from the payload, Go’s template engine renders it as <no value>. Check your test output to catch typos in field paths before going live.

Whitespace inside {{ "{{" }} }} is ignored, so {{ .body.error }} and {{.body.error}} are equivalent.

To include a literal {{ "{{" }} in your prompt (rare), escape it as {{ "{{" }}"{{"{{ "}}" }}.

Volumes

By default, agent containers are isolated Docker environments with no access to your host filesystem beyond the mounted workspace. Volumes let you mount additional host directories into the container — typically credential directories or configuration files that CLI tools inside the container need to authenticate with external services.

Configuring volumes

The agent.volumes list in pylon.yaml defines host paths to mount into the agent container. Each entry uses Docker-style source:target[:mode] syntax:

agent:
  volumes:
    - "~/.config/gcloud:/home/pylon/.config/gcloud:ro"
    - "~/.aws:/home/pylon/.aws:ro"

The mode is optional and defaults to ro (read-only). Set it to rw if the tool needs to write to the mounted directory. Source paths can use ~ to reference the home directory of the user running pylon start.

If you mount a directory containing scripts (e.g. ~/scripts:/opt/scripts:ro), the scripts must be executable (chmod +x) on the host. The agent runs as a non-root user inside the container, so the file permissions must allow execution by that user.

Credential patterns

There are two common ways to pass credentials into agent containers: Environment variables — for service accounts with static tokens. Store tokens in ~/.pylon/.env and reference them in the env block:

agent:
  env:
    SENTRY_AUTH_TOKEN: "${SENTRY_AUTH_TOKEN}"
    GOOGLE_API_KEY: "${GOOGLE_API_KEY}"

Volume mounts — for credential forwarding. Authenticate on the host and mount the credential directory into the container:

agent:
  volumes:
    - "~/.config/gcloud:/home/pylon/.config/gcloud:ro"

Use environment variables when the tool supports them (most CI-oriented CLIs do). Use volume mounts when the tool expects credential files on disk, or when you want to share an existing authenticated session from the host.

Security model

Pylon blocks mounting dangerous host paths to prevent container escape:

/var/run/docker.sock — would let the agent spin up privileged containers
/, /etc, /root — would expose sensitive system files

Volumes default to read-only. Only use rw when the tool genuinely needs write access.

Example: Google Cloud credentials

Authenticate on the host, then mount the credential directory so the agent’s container can use gcloud:

agent:
  volumes:
    - "~/.config/gcloud:/home/pylon/.config/gcloud:ro"
  prompt: |
    Deploy the fix to staging using gcloud.

The agent runs gcloud inside the container, which reads the mounted credentials without needing a separate login.

Config resolution order

When Pylon runs a job it merges settings from both files, with the per-pylon file taking full priority:

Setting	Resolved from
`channel.type`	Per-pylon `channel.type` -> global `defaults.channel.type`
`agent.type`	Per-pylon `agent.type` -> global `defaults.agent.type` -> `claude`
`agent.auth`	Per-pylon `agent.auth` -> global agent defaults -> `oauth` (Claude)
`agent.timeout`	Per-pylon `agent.timeout` -> global `docker.default_timeout` -> `15m`
`agent.volumes`	Per-pylon `agent.volumes` (no global fallback)

Documentation Index

​Examples

​Sentry webhook with approval

​GitHub PR review (no approval)

​Cron audit (scheduled weekly)

​Field reference

​Top-level fields

​trigger

​workspace

​channel

​agent

​Prompt templates

​Template syntax

​Available variables

​Template examples

​Testing template expansion

​Building channel.message interactively

​Tips

​Volumes

​Configuring volumes

​Credential patterns

​Security model

​Example: Google Cloud credentials

​Config resolution order

Examples

Sentry webhook with approval

GitHub PR review (no approval)

Cron audit (scheduled weekly)

Field reference

Top-level fields

`trigger`

`workspace`

`channel`

`agent`

Prompt templates

Template syntax

Available variables

Template examples

Testing template expansion

Building `channel.message` interactively

Tips

Volumes

Configuring volumes

Credential patterns

Security model

Example: Google Cloud credentials

Config resolution order