Pipo documentation

Pipo is a local, self-hosted runtime for continuous pipelines. You describe a pipeline in a .pipo file. Pipo keeps it running and turns every incoming event into a delivered, verified result.

A pipeline has no "done" state, only delivery. Events come in from outside (webhooks, schedules, file changes, chat messages, operating system samples), from inside (the CLI, the dashboard, an agent) or from another pipeline. They pass through a small graph of nodes and are written to one destination: a SQLite table, a file, an HTTP endpoint, a Telegram chat or another pipeline. A packet counts as finished only when Pipo can show it arrived.

pipo: 1
name: heartbeat
input:
  via: schedule
  with: { every: 5s, payload: { status: alive } }
nodes:
  stamp:
    from: input
    transform: map
    with:
      data: { status: "${data.status}", tick: "${meta.source}" }
output:
  from: stamp
  to: file
  with: { path: ./out/heartbeat.jsonl, format: jsonl }
delivered:
  check: line_contains
  with: { value: "${meta.packet_id}" }
  within: 5s

schedule → stamp → JSONL file → line_contains → delivered

Every five seconds this pipeline makes a packet and reshapes it. It appends the packet to a file, then checks that the packet's line is really in the file. If the check fails, the packet is retried or dead-lettered. It is never quietly lost.

The four parts#

The dashboard and its drag-and-drop builder are served by the engine. They read and write the same .pipo files.

Why Pipo#

• Simple. It's built for personal and small-team pipelines. One file is one pipeline, and nothing is hidden in a database.
• Resilient. Every pipeline is an isolated process with its own journal. A packet is written to the journal before its input is acknowledged, and each step's result is committed before the next step runs. After a crash, work resumes from the last committed step.
• Delivery-oriented. "The code ran" is not success. A packet is delivered when the output reports a successful write and the configured delivery check passes.
• Agent-first. An agent can write a pipeline, run it, step in while it's running and step out again, through the same documented interfaces a person uses: the file format, the CLI, REST and MCP. Agent access and edits are limited by explicit policies.

What Pipo isn't#

• Not a workflow or approval tool. Pipelines have no human-approval steps or BPM-style processes. (You do approve the pipelines agents write before they run: see Agents that build pipelines.)
• Not multi-tenant or hosted. It runs on your machine or your own server, with one owner and no other users or roles. It binds to 127.0.0.1 by default; exposing it takes the owner's login and a public URL (see Owner and remote access).
• Not exactly-once. Pipo guarantees at-least-once delivery, plus idempotency keys at the output. A side effect in the middle of a pipeline can run twice after a crash. See Core concepts.
• Agents don't change engine code. They change .pipo files through a validated, audited protocol.

Pipo runs on Linux and macOS.

Where to go next#

The specification is the full, precise definition of the format and the runtime. These guides explain the same rules with more examples.