Penstock v0.5.3 · Cistern v0.3.1
A self-hosted AI agent that reads only what you share.
A self-hosted AI agent: Penstock and Cistern running together on your machine. It runs on the model you choose (a local Ollama, Copilot, Anthropic or OpenAI), remembers what you taught it, reads only the data you shared, and gets a receipt for every read.
Headworks is a self-hosted AI agent you can hand real work to. It runs on your own machine, with a model you pick, in the folder you give it to work in. When it needs something from your Cistern pod, it has to ask. You decide, and you can change your mind: take the access back and its very next request is refused. Every yes and every no is written down where you can read it. That's Headworks: two open-source parts, running together. Penstock is the assistant, and it keeps a record of its work. Cistern is where your data lives, and the gate in front of it.
pod tool, using a credential of its own by default, not yours. Cistern checks your grant, then either hands the file over or says no. Either way, it writes a receipt. Revoke the grant, and the next ask gets a no.
One task, start to finish
Here's what happens when you hand it a piece of work.
the work
Give it a task and a folder to work in. Grant it the parts of your pod it may read.
then work
With memory on, the parts of your record that match the task go into the model's prompt first. Then it plans and uses its tools, on the model you chose.
the grant
When it needs something from your pod, Cistern checks your grant on that request. Nothing is cached.
down
Cistern receipts the allow or the deny. Penstock logs each model and tool call when it stores to a database.
What it remembers
Its memory is plain files you own and can read, change or delete. It goes into the model's prompt; Penstock doesn't train a model on it.
happened
A script you run drafts one from a finished task's PR and commits: what was asked, decided, refused, learned, and what is still open. You edit the draft.
now believe
A script you run proposes them from the episodes' learned lines, and you choose which to keep. One per file, with where it came from. A changed mind supersedes the old fact; it is never quietly overwritten.
built before
For a task worth repeating, a script you run scaffolds one from its changes: the decisions, a skeleton and a check. You review it like any other change. With memory on, a matching pattern joins the prompt, space permitting.
Each fact, episode and pattern the agent loads is written to its audit log when Penstock stores to a database, so you can see what it remembered and when. Memory stays off until you turn it on. Next, on Penstock's main branch but not in a release yet: patterns the agent loads only when it needs them, and a free, public set of starter patterns for common stacks, global memory. unreleased
What each part does today
Each line is something a released part does today, except the one tagged planned. We checked every one against that part's release tag.
- Works on your data
- Penstock runs on your own hardware, with the model you choose, a local one included. When it needs your data, it goes through its
podtool to a Cistern pod. v0.5.3 - Remembers
- Penstock keeps a record of what you asked, what was decided, what was refused and what it learned, as plain files you own. Turn memory on (it's off by default in the web and IDE modes) and it reads that record before it answers. Split the record into projects, and each project sees its own section, never another's. More on the record it keeps. in Penstock v0.5.3
- Sees only what you share
- Cistern checks your grant on every single request. It never caches a decision, so when you take access back, the very next request is refused. v0.3.1
- Keeps a receipt
- Cistern writes down every allow and every deny, and you can look them up file by file. Penstock logs every model call and tool call to its audit log when it stores to a database.
- Learns how you work
- A persona that answers from your record, points to the card behind each decision, and asks you when the record has nothing to say (penstock#93). planned
Try them together
Two ways, each straight from the parts' own docs, with every step linked. Both run on your machine and listen only on 127.0.0.1.
- One command
- Cistern's demo brings up a pod and Penstock with a single
docker composecommand, the agent on its own credential. Then it walks you through five beats: put a file in, watch the agent get refused, grant access, watch it read, revoke, and watch it get refused again. The demo pins Penstock 0.2.0, an older release. The demo → in Cistern v0.3.1 - The latest of each
- Want the newest releases? Wire them yourself in three steps.
Start Cistern from its quickstart: one container, an owner token, and your data on your own disk. Run it →
Give the agent its own credential, a service principal, so the pod can tell it apart from you. INTEGRATION.md, step 1 →
Set CISTERN_BASE_URL and CISTERN_AGENT_TOKEN on Penstock, then grant the agent a folder. Configuration reference →
Until you grant it a folder, the agent is refused every time, and each refusal gets a receipt too. That's the default, not a setting.
Where it stands today
What has shipped, its limits, and what is planned.
- Shipped
- Both parts, each on its own release: Penstock v0.5.3 and Cistern v0.3.1, with the
podtool between them. live - Its limits
- The one-command demo still uses an older Penstock; for the latest of each, wire them by hand as above. Run Penstock on your own machine, not on a network: v0.5.3 passed a stranger test with nothing blocking, and two documentation fixes are under way (penstock#171). Cistern's remote MCP door isn't open yet (cistern#220), so an assistant reaches the pod through its local bridge.
- Planned
- The persona (penstock#93). planned
- Licence
- Apache 2.0, both parts. Free for any use, commercial included.