Configuration

Pipo keeps its state and settings in one folder, the Pipo home. Pipeline files hold everything about one pipeline. The home holds what's shared by all of them: the engine's settings, agent provider settings, bots, trust, journals, logs and the runner registry.

The Pipo home#

The home is, in order of precedence:

1. --home <dir>, on any pipo command (and pipod, pipo-runner);
2. the PIPO_HOME environment variable;
3. ~/.pipo.

Everything that talks to the same pipelines must use the same home: the engine, the CLI, pipo run and chained pipelines. A throwaway home is a good way to experiment without touching your real one:

export PIPO_HOME=/tmp/pipo-play
pipo run examples/heartbeat/heartbeat.pipo

Layout#

A pipeline's journal outlives its runner: pipo packets, inspect, dlq, history and diff read it when the pipeline is stopped. Delete pipelines/<name>/ to forget a pipeline completely. Data in journals is removed over time by each pipeline's retention settings (see Lifetime, concurrency and retention).

config.yaml#

engine:
  listen: 8787                  # serve the gateway (REST, SSE, MCP, the dashboard) on 127.0.0.1:8787
  auth: owner                   # the default: the dashboard needs the owner's login (open: no login)
  detached: false
  idle: 5m
  ttl: 8h
  timezone: Europe/Stockholm
  env_allow: [DEPLOY_ENV]
  workspace: /home/me/pipelines
  agent_budget:
    per_day: 10.00
  restart: { backoff: 1s, max_backoff: 30s, stable: 1m, max_restarts: 5, window: 10m }
  mcp:
    auto_approve: false
    tokens:
      - { name: ops-agent, token: env:PIPO_MCP_TOKEN, scope: operate, pipelines: [people-intake] }
agents:
  claude_api:
    api_key: op://Pipo/anthropic/api-key
    pricing:
      claude-sonnet-5-5: { input: 3, output: 15 }

Only two top-level keys exist, engine and agents. Unknown keys are errors, so a typo never falls back to a default silently. Every problem is reported at once, with its line and column. The engine reads the file when it starts, so restart it after a change (pipo engine stop, then any command). Runners read agents:, engine.timezone and engine.agent_budget themselves, at their own start.

engine:#

Durations are written like 500ms, 30s, 5m, 1h or 7d.

engine.restart controls crash restarts. A crashed runner is restarted after backoff, doubling on each crash up to max_backoff. A runner that ran at least stable before crashing starts again from backoff. More than max_restarts crashes within window mark the pipeline crashed, and it stays stopped until you start it.

engine.mcp.tokens entries:

agents:#

Settings per agent provider. Each provider's map is merged over its defaults, so you only write what you change.

agents:
  claude_api:
    pricing:
      claude-sonnet-5-5: { input: 3, output: 15 }
  claude_code:
    command: /usr/local/bin/claude
  codex:
    pricing:
      gpt-5: { input: 1.25, output: 10 }

A problem in agents: refuses the start of any pipeline with agent nodes, with the problem named. See Agent nodes.

bots.json#

{
  "telegram": {
    "default": "main",
    "bots": {
      "main": { "token": "env:TELEGRAM_MAIN_TOKEN", "allow": [123456789], "poll_every": "25s" }
    }
  }
}

Each bot has a token (raw, or an op://…/env:… reference), an allow list of chat or user ids, an optional poll_every and an optional api (another Bot API server). The dashboard's 🤖 Bots page writes it. A change applies from a pipeline's next start. See Telegram bots.

trust.json#

pipo trust <template> records a template's content hash here, so fn modules and exec nodes in projects made from it pass pipo check (P052). Editing a trusted file means trusting it again. You don't need to edit this file by hand. See Templates and generators.

The runner registry#

While a runner runs, it keeps run/<name>.json up to date, written atomically, and removes it on a clean stop:

{ "pipeline": "people-intake", "version": 3, "pid": 41822, "socket": "/home/me/.pipo/run/people-intake.sock",
  "listen": 8081, "detached": true, "ttl": "30m", "state": "active",
  "started_at": "2026-10-03T09:12:44Z", "engine_id": "e_01J9…" }

listen and ttl are the port and the --ttl the pipeline was started with, so restarts and reattaches reuse them. A runner polling a Telegram bot also records the bot's id there, so a second pipeline can't poll the same bot. The engine and pipo runners use these entries to find runners, including detached ones that outlived an engine. See The engine.

Logs#

Each runner writes its log to logs/<name>.log:

pipo logs people-intake -f            # follow it
pipo logs people-intake --node enrich # one node's lines

pipo run writes the log to the terminal instead. Secrets are redacted from every log line.

Environment variables#

Your own variables reach pipelines in two ways:

• env:VAR secret references (secrets:, api_key, MCP tokens, bot tokens) read the variable from the environment of the process that resolves them: the runner for pipeline secrets, the engine for MCP tokens. A runner started by the engine inherits the engine's environment.
• env.NAME in expressions only sees the variables listed in engine.env_allow (or pipo run --env-allow A,B).

See also#

• The engine
• Secrets
• REST, SSE and MCP