Penstock v0.5.3 · Cistern v0.3.1
Headworks: the parts, working as one.
An AI assistant that works on your data, remembers what you have taught it, sees only what you have shared, and keeps a receipt for everything.
A headworks is where water enters a scheme: the cistern holds it, the penstock carries it to where the work is done, and nothing passes the gate unless it is let through. Headworks is the name for the two open-source parts below when they run together. Penstock is the agent that does the work and keeps the record of it. Cistern holds your data and decides, on every request, whether the agent may read it. Each promise below names the part that keeps it and the release it shipped in.
pod tool asks Cistern for a file, by default with a credential of its own. Cistern checks the owner's grant, answers or refuses, and writes a receipt either way. Revoke the grant and the next request is refused.
Four promises, and who keeps each
Each line is something a released part does today, checked against that part's release tag.
- Works on your data
- Penstock runs the agents: self-hosted, on models you choose, a local one included. Its
podtool is how it reaches a Cistern pod. v0.5.3 - Remembers
- Penstock's record: what was asked, decided, refused and learned, as plain files you own. With memory turned on (it is off by default in the web and IDE modes), the record is recalled before the model writes, and with a root split into projects, each project loads its own section and never another's. More on the record it keeps. in Penstock v0.5.3
- Sees only what you share
- Cistern holds your data and enforces the owner's grants on every request. No decision is cached, so a revoke holds from the very next request. v0.3.1
- Keeps a receipt
- Cistern receipts every allow and deny, and the owner queries them per resource. Penstock writes every model call and tool call to its audit log when database storage is on.
- Learns how you work
- The persona: a companion that speaks from your record, cites the card behind each decision, and asks when the record is silent (penstock#93). planned
Two ways, from each part's own docs
Every step links the shipped doc it comes from. Both run on your own machine, with ports bound to 127.0.0.1.
- One command
- Cistern's demo starts a pod and Penstock together with one
docker composecommand, the agent on its own credential, then walks five beats: put a file in, watch the agent be refused, grant, read, revoke and be refused again. Its compose file pins Penstock 0.2.0, not the latest release. The demo → in Cistern v0.3.1 - The latest of each
- Wire the current releases yourself in three steps.
Start Cistern from its quickstart: one container, an owner token, data on your own disk. Run it →
Give the agent a credential of its own, 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 the owner grants it a folder, every request the agent makes is refused, and the refusal is receipted too. That is the default, not a setting.
Where it stands
Nothing on this site is announced before it has run. This is the honest state.
- 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
- Headworks has no release of its own yet: the demo pins an older Penstock, and the latest of each is wired by hand as above. Penstock should run on your own machine, not on a network, until it clears the stranger test Cistern is held to. Cistern's remote MCP door is not reachable yet (cistern#220), so an assistant reaches the pod over its local bridge.
- Planned
- The persona (penstock#93). planned
- Licence
- Apache 2.0, both parts, free for any use including commercial.