Penstock

Guide / Set up a project

Files Penstock reads and writes

A complete list of the files Penstock reads, writes and keeps, and where each one lives.

Free

In your project

FileWhat it isCommit it?
penstock.yaml (also .yml, .json)The project's settings. Read from every folder from the root down to the diagram.Yes
penstock.local.yamlThis machine's settings, and the engine address you type into the Connection dialog.No. Penstock adds it to .gitignore.
.bpmnlintrcYour bpmnlint rules.Yes
.camunda/element-templates/Element templates, read from next to a diagram and every folder above it.Yes
penstockw, penstockw.cmd, penstock/wrapper/penstock-wrapper.propertiesThe command line wrapper and the version it pins.Yes
penstock-baseline.jsonThe problems the project already has. Written by penstock check --update-baseline.Yes
.penstock/runs/Traces of test-case runs. It has its own .gitignore.No
.penstock/images/Pictures from penstock diff --images and penstock report.No
penstock-report.mdThe pull request report written by penstock report.No
.bpmn, .dmn, .formYour diagrams, decisions and forms. Penstock edits them in place.Yes
.cmmn, .cmmn11.xmlCase models. Penstock only reads and draws them; it does not edit them. See CMMN case models.Yes
<name>.dmn.tests.jsonThe saved test cases of a DMN file, next to it. See DMN tests.Yes
.penstock/deployments.jsonWhat was deployed to each environment: a hash and a version for each resource, with no timestamps. The baseline for drift. See Drift, promote and protected environments.Yes
.penstock/policy/, penstock.policy.lockThe policy pack and its pin. See Policy pack.Yes
.penstock/receipts/Verification receipts of AI changes. Written only with ai.verify.keepReceipts: true. See AI receipt and auto-repair.Your choice
.penstock/migration-selection.jsonThe changes you accepted in the migration workspace. Written only when you choose Save selection. See Camunda 7 to Camunda 8.Your choice
Evidence packsA zip or a folder written by penstock evidence build, by default under .penstock. See Evidence pack.Your choice

In your home folder

Penstock keeps its personal files in ~/.penstock. If the environment variable PENSTOCK_HOME is set, they are under that folder instead. Every tool on the machine shares them.

FileWhat it is
preferences.jsonYour toolbar choices, whether the tour was seen, the editor theme, the width of the sidebar and the tab you left selected in each editor, whether the palette is folded, Sketchy drawing, tree or flat view of the project model, the last export format, the suggestion switches, and the AI chat: where it is shown, which agents are on and the model of each. Readable only by you, and replaced whole, never half written. A file that cannot be read is kept as preferences.json.bak before a new one is written. See penstock.yaml.
chats/<project>/The chats of the AI agent, one file for each chat with its title, its messages and the files it touched, in a folder for each project. Readable only by you. Deleting a chat in the editor removes its file. See AI chat.
agents/The list of agents from the ACP Registry as last fetched, with its icons; the agents Penstock installed for you; and the models each agent offered the last time they were read. See AI agents.
agent-hub/A small record for each project, so every window and tool finds the one agent session the project shares: a port on this machine (127.0.0.1) and a token. Readable only by you, and removed when the session ends.
license.jsonThe signed licence token and a clock mark, never a key, a tier or a date you could edit. Readable only by you. See Buying and signing in.
clock.json, pipeline.jsonThe latest time the machine has seen, kept beside the licence so a clock set back is noticed, and the short-lived token of a pipeline run.
trusted-projects.jsonThe projects you have trusted to run a deploy hook, the project's command line and its lint rules. Trusting in one tool trusts in the others. Settings in your tool list them, and penstock trust --list prints them.
connectors/<release>/The Camunda connector templates downloaded from GitHub.
wrapper/dists/<version>/The command line versions the wrapper downloaded.
test-builds.jsonA list of test builds a test-case run deployed, so the next run can remove what an interrupted one left.

Not in a file

The password or client secret for a deployment profile lives in the secret store of your tool. It is never written to a file.

Where the secret lives

JetBrains

The IDE password safe, once for each profile. Older versions also kept settings in .idea/bpmn-project.xml. That file is legacy. Penstock offers to move its settings into penstock.yaml.

VS Code

VS Code's secret storage, once for each workspace, profile and field. Nothing is written to a file.

Command line

There is none. Give the secret to a command through the environment: PENSTOCK_PASSWORD, PENSTOCK_CLIENT_SECRET or PENSTOCK_TOKEN.

How to remove everything

  1. Remove Penstock from your tool. See below.
  2. Delete ~/.penstock.
  3. In your projects, delete the files above that you do not want.

Remove Penstock from your tool

JetBrains

Open Settings | Plugins and the Installed tab, choose Penstock, press Uninstall and restart the IDE. Your diagrams stay as they are.

VS Code

Open the Extensions view, find Penstock and press Uninstall. Your diagrams stay as they are. See Installing in VS Code.

Command line

Delete penstockw, penstockw.cmd and penstock/wrapper from your project. If you installed the command with npm, run npm uninstall -g @kern0x1b/penstock-cli. penstock init --hooks wrote a pre-commit hook into .git/hooks: delete that file too. Penstock keeps a few small files of its own in ~/.penstock, which you can delete.

What you see

Common problems

My toolbar differs between two computers.
preferences.json is per machine. It does not sync.
I want the settings somewhere else.
Set PENSTOCK_HOME to another folder, for example on a shared drive. Then every tool uses that folder.
Git shows penstock.local.yaml as new.
Add it to .gitignore. penstock init does this for you.