How to use Pi Durable

1. 01Alejandro 8:27

   It's a building block, not an app

   You can't type pi durable and chat. It's a code library. You, or your coding agent, use it to build an agent that runs on its own.

   How
2. 02Alejandro 6:18

   Every step is saved before the next one

   Each model call and each tool call is saved as a task with a checkpoint, in a file on disk. Nothing important lives only in memory.

   How
3. 03Alejandro 7:25

   Crash, restart, carry on

   If the program dies, the next run opens the same file, finds the unfinished work and continues it. Nobody has to type continue.

   How
4. 04Dan, on-call 4:38

   Risky actions don't run twice

   A tool cut off by a crash only runs again if it's marked safe to repeat. Otherwise the agent is told it was interrupted and decides what to do.

   How
5. 05Dan, on-call 14:53

   One agent, many screens

   The agent lives on one machine. A browser, a terminal, a phone or a script can all connect to it and see the same thing.

   How
6. 06Dan, on-call 7:56

   Shared notes every agent can read

   Agents can keep app state, like a to-do list or an incident report, saved right next to the chat. Other agents can read it too.

   How
7. 07Dan, news 2:38

   Proactive means it works first, then waits

   Durable agent plus a trigger plus its own machine. Something happens, the agent starts, does the work, then waits for your OK.

   How
8. 08Alejandro 15:13

   It's experimental. Pin the version

   Released Oct 1, 2026, already at 1.3.0, and the code has changed between releases. Lock the version you build on.

   How

Agent

An AI model that can do things, not just talk: read files, run commands, search the web, then decide the next step from what came back.

Pi

A small, open-source coding agent you run in the terminal by typing pi. From Earendil, the team of Mario Zechner and Armin Ronacher. Version 1.0 shipped Oct 1, 2026.

Pi Durable

A code library from the same team for building agents that survive crashes and keep running when nobody is watching. Shipped with Pi 1.0. Experimental.

Harness

The program around the model. It sends your message, runs the tools the model asks for, saves the chat, and loops. Pi has one. Pi Durable is another.

Library (npm package)

Code you add to your own program with one install command. You don't open it like an app. Pi Durable is the package @earendil-works/pi-durable.

Node.js

The program that runs JavaScript and TypeScript outside a browser. Pi Durable needs version 22.19 or newer. Alejandro's demo needs 24.

Tool call

When the model asks the harness to do something for it, like read a file or send an email. The harness runs it and hands back the result.

Conversation

One chat between you and an agent, saved as a list of messages. If you've used Pi, think of a Pi session. One harness can run many at once.

Submission

One thing you hand a conversation, usually a message. You get back an ID, so you can wait for the answer now or check on it later.

Task

A saved unit of work: one model call, one tool call, or a longer job you define. Pi Durable runs everything as tasks.

Checkpoint

The note a task saves before it moves on: where it is and what it has done. After a crash, work restarts from the last one.

Storage

Where it all gets saved. SQLite (one file on disk) for real use, a JSONL folder, or memory, which forgets everything when the program stops.

SQLite

A small database that lives in one file. Nothing to install or run separately. Newer versions of Node have it built in.

Registry and extensions

The registry is the list of add-ons this program loaded. An extension is one add-on: a bundle of tools, system prompt parts and rules.

Replay-safe

A tool that's fine to run twice, like reading a file. Mark a tool replay: "safe" and it reruns after a crash. Everything else is unsafe unless you say so.

Idempotency key

A unique label on an action, so if it's sent twice it only happens once. Pi Durable calls its version a requestId.

Daemon

A program that runs in the background and is started again automatically if it stops. Pi Durable resumes when it's restarted, but it doesn't restart itself.

Client

A screen that connects to the agent: a web page, a terminal app, a phone, a curl command. The agent keeps running when you close it.

Trigger

The thing that starts an agent without you typing: a clock (cron), a new line in a log, a webhook, a message in Slack.

Cron

The built-in scheduler on Mac and Linux. One line says run this every minute, or every morning at 9.

Proactive agent

IndyDevDan's term: an agent that starts work when something happens, then waits for you to review. A durable agent, plus a trigger, on its own machine.

In, near, out of the loop

In: you prompt back and forth. Near: the agent works and you approve. Out: it runs without you. IndyDevDan's ladder.

Sandbox

A separate machine or box where an agent can't hurt your own files. Dan uses spare Mac minis and exe.dev cloud machines.

Compaction

Summing up older messages so a long chat still fits in the model's memory. Pi Durable does it in the background and keeps the old messages saved.

Fork

A copy of a conversation from some point on, so you can try a different direction without losing the first.

Jev

A fast, very cheap classifier model from TypeSafe. Dan uses it to sort every log line or news story before a pricier model sees it.

llama.cpp and Qwen

llama.cpp runs AI models on your own computer for free. Qwen3.5-0.8B is the tiny open model Alejandro runs on it.

Local model

A model that runs on your computer instead of a company's servers. Free and private, but small ones make more mistakes.

const models = createModels();
models.setProvider(openaiProvider());

The six steps and their order are Alejandro's. The code lines are shortened from the package README and his demo; the three run-time boxes are FakeNerd's split of what the announcement describes.

npm install @earendil-works/pi-durable @earendil-works/pi-ai @earendil-works/chord

import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
import { createModels } from "@earendil-works/pi-ai/models";
import { openaiProvider } from "@earendil-works/pi-ai/providers/openai";
import { AssistantEntry, createRegistry, Harness, MemoryStorage } from "@earendil-works/pi-durable";

const context = BACKGROUND_CONTEXT;

const models = createModels();
models.setProvider(openaiProvider()); // reads OPENAI_API_KEY

const harness = await Harness.open(new MemoryStorage(), { models, registry: createRegistry() }, context);
const root = await harness.root(context, { agent: { model: { provider: "openai", modelId: "gpt-6-sol" } } });

const submission = await root.submit({ type: "input", content: "What is the capital of France?" }, context);
const settled = await submission.wait(context);
if (settled.status === "done" && settled.type === "input") {
	const answer = await root.commit((tx) => tx.entry(AssistantEntry, settled.answer), context);
	console.log(answer?.model?.[0]);
}
await harness.close(context);

import { openNodeSqliteStorage } from "@earendil-works/pi-durable/storage/sqlite/node";

const harness = await Harness.open(await openNodeSqliteStorage("./session.sqlite"), { models, registry }, context);
const root = await harness.root(context); // the same root as last time
harness.resume(); // continue any run the last process left unfinished

import { Type } from "@earendil-works/pi-ai";
import { defineTool } from "@earendil-works/pi-durable";

const searchIssues = defineTool({
    name: "search_issues",
    description: "Search the issue tracker",
    parameters: Type.Object({ query: Type.String() }),
    replay: "safe", // only reads, so a rerun after a crash is fine
    execute: async (args, api) => {
        // streamed to every client watching
        api.output(`searching for ${args.query}\n`);
        return {
            output: [{ type: "text", text: await tracker.search(args.query) }],
        };
    },
});

More: the package README and its 32 numbered examples, from a one-line conversation to a reload-and-restart. That folder is what Earendil says to point your agent at.

1. 1It's experimental"The API changes without notice between releases." Tool results were renamed from content to output in 1.2.0. The two demo apps in the announcement were removed from the main branch on Oct 12. · README, CHANGELOGDo: Pin an exact version in package.json. The three demo repos pin 1.2.0, 1.0.3 and 1.1.0.
2. 2Tools aren't safe to repeat by defaultAfter a crash, a cut-off tool reruns only if it says replay: "safe". Even then, an email, a payment or a deploy could happen twice. · Announcement, spec, every demo READMEDo: Mark only read-only tools safe. Give anything that sends, pays or deploys its own idempotency key.
3. 3It doesn't restart itselfRecovery happens when your program opens the storage again. If nothing starts it, nothing resumes. · Alejandro's video description and READMEDo: Run it under a service manager (launchd on Mac, systemd on Linux), or start it from cron.
4. 4One program per storage file"One process owns a storage at a time; there is no cross-process locking." · READMEDo: One running copy per SQLite file. Alejandro's demo adds a PID file to guard it.
5. 5It's not a sandboxThe coding tools run with your permissions. Alejandro's demo prints: tools run with your user permissions. This is NOT a sandbox. · Alejandro's README, Pi's READMEDo: Use a throwaway folder, a container, or a separate machine like Dan's.
6. 6It ignores your Pi setupNo .pi folder, no AGENTS.md, no skills. A conversation only gets what you pass in code. · Alejandro, 16:47Do: Put the instructions in the conversation's instructions field, or load your AGENTS.md text yourself.
7. 7Memory storage forgetsMemoryStorage is lost when the program stops. JSONL keeps the whole history in memory too. · READMEDo: Memory to try things. SQLite for anything you want to survive.

1. 01

   Check you have Node 24

   Free

   Open Terminal and type this. You need v24 or higher for Alejandro's demo. If it's missing or older, install the LTS from nodejs.org.

   Step 1 · in Terminal

   ⧉Copy

   node --version

   nodejs.org
2. 02

   Meet Pi first (optional, 5 minutes)

   Free install. The model costs whatever your plan costs

   Install Pi, open it in any folder, and connect a model with /login. You don't need Pi to run Durable, but it's the friendliest way to have an agent explain and change the code for you in step 6.

   Step 2 · in Terminal

   ⧉Copy

   curl -fsSL https://pi.dev/install.sh | sh
   pi
   
   # then, inside Pi, type:
   /login

   Pi quickstart
3. 03

   Run Alejandro's demo with no model

   Free

   It runs on a built-in echo model: no key, no download. You'll see a banner with the tools and the SQLite file, then it repeats what you type. Type /quit to leave.

   Step 3 · in Terminal

   ⧉Copy

   git clone https://github.com/alejandro-ao/pi-durable-demo.git
   cd pi-durable-demo
   npm ci --ignore-scripts
   npm run chat

   The demo repo
4. 04

   Give it a real brain, still free

   Free. Prefer a cloud model? Put OPENAI_MODEL and OPENAI_API_KEY in .env instead

   Install llama.cpp and start the tiny Qwen model in a second Terminal window (the brew line is for a Mac; llama.cpp's page covers Linux and Windows). The first run downloads the model. Then start the chat and ask: Read README.md and tell me the secret phrase.

   Step 4 · in Terminal

   ⧉Copy

   # second window: install and start the model
   brew install llama.cpp
   llama-server -hf unsloth/Qwen3.5-0.8B-GGUF:BF16 --alias qwen3.5-0.8b-bf16 --jinja --reasoning off -c 16384 --parallel 1 -ngl 999 --host 127.0.0.1 --port 8080
   
   # first window, inside pi-durable-demo:
   npm run chat:llama

   llama.cpp
5. 05

   Crash it on purpose

   Free

   Start the resume version. Ask it to read the docs and say what the project does. Press Ctrl+C while it's working. Run the same command again and watch the answer arrive. This is the whole point of Pi Durable, in one minute.

   Step 5 · in Terminal

   ⧉Copy

   npm run chat:resume:llama

6. 06

   Have your agent explain it and change it

   Your agent's usual cost

   Open Pi, Claude Code or Codex in the demo folder and paste the first starter prompt below. Then ask for one small change, like a new instruction or a tool. This works in Cloudroom or bb too.

   Starter prompts
7. 07

   See a proactive agent, still free

   Free in this mode. Live mode needs an OpenRouter key: about $0.32 the first sweep, then under a cent

   Dan's news agent has a free offline mode with fake news and a scripted model. It needs just (brew install just). Open http://localhost:4851 when it's up.

   Step 7 · in Terminal

   ⧉Copy

   git clone https://github.com/disler/pi-durable-news-agent.git
   cd pi-durable-news-agent
   just install
   cp .env.example .env
   just api tokens
   just combos dev

   The news agent repo
8. 08

   The full on-call demo, when you're ready

   About $0.09 per incident, per the repo

   The one in Dan's video: Jev watches logs, an agent fixes the bug, the deploy waits for you. It has the most moving parts and needs an OpenRouter key. Follow the repo's README, or let your agent run its /install command.

   The durable-pi repo

Commands for steps 3 to 5 are from Alejandro's README; step 7 from Dan's; step 2 from pi.dev. The order and the step 1 check are FakeNerd's.

• Pi workflow How Armin Ronacher, one of Pi's makers, works with the Pi coding agent day to day.You want to use Pi itself well
• Guillermo Rauch's workflow fx, Vercel's small terminal agent and its library, with the brain-and-hands picture.You want another small harness to compare
• Autoresearch Leaving an agent running for hours or days on one goal.You want long runs, not always-on
• Jev The cheap classifier in both of Dan's builds, with prompts and the wiki.You want the filter in front of your agent

• Pi Durable EXPLAINED: Build Always-On Agents with Local Models by Alejandro AO on the Hugging Face channel (Oct 19, 2026). The definition, the Pi family picture, the five-email example, the six steps and the restart demo are his, in our words. His demo repo has no license file, so this page links to it and quotes single lines only.
• Two videos by IndyDevDan: Pi Durable PROACTIVE Agents: Jev Triggers My ON-CALL Pi Agent (Oct 12, 2026) and My Jev Pi Durable Agent CURATES News: HYPE, FACT, or SIGNAL (Oct 19, 2026). Proactive agents, the formula and the in-near-out ladder are his. He sells courses (Tactical Agentic Coding, and a Phase 3 course in pre-sign-up) and plugs them in both videos; those parts are left out. He says he takes no sponsorships. His repos are MIT. Costs and claims about the big labs are his and were not checked.
• Pi and Pi Durable by Earendil, MIT. Package facts, code and quotes are from the announcement (signed Earendil Engineering), the Pi 1.0 post, and the package README and changelog, read Oct 19, 2026.
• Jev is made by TypeSafe. FakeNerd's own notes on it are on the Jev card.
• Captions were read, not the screen; where a caption and a repo disagreed, the repo won. The map's run-time split, the walkthrough wording, the examples grouping, the step order in Try it, the three starter prompts and the takes are FakeNerd's. Not sponsored by anyone on this page.