Install

Pipo runs from a checkout of its Git repository. There is no packaged release yet. The install script does every step for you and then checks the result. You can also install by hand.

Install script#

curl -fsSL https://raw.githubusercontent.com/ramigb/pipo/main/install.sh | bash

The script:

1. Checks the platform (Linux or macOS) and the prerequisites. It offers to install Bun and Rust if they're missing or too old. It only gives you the command for a C compiler or Git, because those need sudo.
2. Looks for an existing install: a checkout in ~/.local/share/pipo, or the checkout your pipo command runs. If it finds none, it clones the repository into ~/.local/share/pipo. If it finds one, it fetches. When the upstream branch has new commits, it lists them and asks before updating (a fast-forward only). It never updates a checkout with local changes or local commits. If the update changes the install script, the new script finishes the install.
3. Runs bun install, which also builds the runner.
4. Links the pipo command into Bun's global bin folder (~/.bun/bin).
5. Verifies the install. It runs the runner binary and pipo check examples, runs pipo test on examples/people-intake through the runner, and starts an engine in a throwaway Pipo home, loads the dashboard, then stops the engine. It also lists the optional tools it finds.
6. If an engine from this checkout is running the code from before the update, offers to restart it with pipo engine restart. Its pipelines drain and start again on the new code, and detached runners keep running. See Restarting the engine.

In a checkout you already have, run ./install.sh there. It installs that checkout, and offers to update it the same way.

The script exits with status 1 if a check fails, and prints what to do for each failure. Run ./install.sh --check from the checkout at any time to check the install again.

Prerequisites#

Optional, depending on what your pipelines use:

• 1Password CLI (op), signed in, for op:// secret references. See Secrets.
• A coding-agent CLI (claude, codex, pi or opencode), installed and logged in, for CLI agent nodes.
• Any program an exec step runs, such as ffmpeg or pandoc. See Running programs.

Clone and install#

git clone https://github.com/ramigb/pipo.git
cd pipo
bun install

bun install installs the TypeScript dependencies, then builds the runner with cargo build --release -p pipo-runner. The binary lands in target/release/pipo-runner. The first build takes a few minutes. Later builds are incremental.

If cargo isn't installed, bun install still succeeds. It prints a hint instead of building the runner. Install Rust, then build it:

bun run build:runner

You don't need to rebuild by hand after pulling changes. Whenever pipo needs the runner and the binary is missing or older than the crate's sources, it builds it again first. A run that rebuilds takes longer to start.

Get the pipo command#

From the repository root, bun pipo … always works, because the root package.json has a pipo script:

bun pipo --help
bun pipo check examples

To run pipo from any folder, link the CLI package. bun link registers it and puts a pipo executable in Bun's global bin folder (~/.bun/bin, which the Bun installer adds to your PATH):

cd packages/cli
bun link
cd ../..
pipo --help

The link points at your checkout, so git pull updates the command too.

If you'd rather not link, an alias works as well. Add this to your shell profile, with the path of your checkout:

alias pipo="bun $HOME/src/pipo/packages/cli/src/main.ts"

The rest of these docs write commands as pipo …. From the repository root without a link, write bun pipo … instead.

Check the install#

./install.sh --check, from the checkout, runs every check the install script runs. Or check by hand:

pipo check examples

Every example should report ok. Then try one in the foreground:

pipo run examples/heartbeat/heartbeat.pipo

It logs started v1 and appends a line to examples/heartbeat/out/heartbeat.jsonl every five seconds. Press Ctrl-C to drain and stop it.

Where Pipo keeps its state#

Everything Pipo writes at runtime lives in one folder, the Pipo home: ~/.pipo by default. Set PIPO_HOME, or pass --home <dir> to a command, to use another one.

~/.pipo/
  config.yaml                  engine and agent settings (optional)
  owner.json                   the owner: username, password hash, optional email
  sessions.json                the owner's dashboard sessions (digests only)
  engine.key                   the key the CLI sends instead of a login
  bots.json                    Telegram bots (made from the dashboard)
  trust.json                   trusted templates and projects
  approvals.json               pipelines agents wrote, and their approval
  mcp-grants.json              agents connected over OAuth (token digests only)
  pipelines/<name>/journal.db  each pipeline's journal
  pipelines/<name>/files/      files downloaded by a telegram input
  run/<name>.json              runner registry entries, and their sockets
  run/engine.json              the running engine
  logs/<name>.log              each runner's log, and engine.log

Your .pipo files live wherever you like, usually in a project folder or Git repository. See Configuration for config.yaml.

Editor support#

The VS Code extension in packages/vscode registers .pipo files, attaches the JSON Schema for completion and hover help, and highlights ${…} templates. See Editor support.

Updating#

git pull
bun install

Or run the install script again. It shows what's new, asks before updating, then installs and checks. ./install.sh --check only tells you whether an update is available.

If an engine is running, restart it so it runs the new code: pipo engine restart. The dashboard shows a banner when the running engine is older than the code on disk. See Restarting the engine.

Uninstalling#

Stop everything (pipo engine stop, then pipo stop <name> for any detached runners pipo runners still lists). Then remove the checkout, the link (cd packages/cli && bun unlink) and, if you no longer need the journals, the Pipo home.

Next: Quick start.