Penstock

Guide / Start here

Penstock Web

Penstock Web is the BPMN, DMN and form editors in a browser tab, for a project folder on your own machine. One command starts it, and the window around the editors is a project tree, tabs for your files and a sidebar of actions, with no editor or plugin to install.

Free The command line, which needs Node.js 22.22.2 or later. Features that are Pro elsewhere are Pro here too.

Start it

  1. Install the command line: npm install -g @kern0x1b/penstock-cli.
  2. In a terminal, run penstock web with the folder of your project: penstock web ./processes. Without a folder it starts on a welcome page.
  3. Open the link it prints. A browser opens on it by itself.
  4. Work in the page. Stop the server in the terminal where it runs.

Everything stays on your machine. The page can be used only through the link the command prints, which holds a key that is new on every run. The options, the key and what the server will and will not do are on penstock web.

Open a project

With no folder given, the page opens on Open a project, which says Choose the folder that holds your diagrams, decisions and forms. Nothing leaves this machine. Under it are the recent projects, each with a button to take it off the list. A project whose folder has gone is disabled and says Folder not found.

  1. Press Open a project…. A folder browser opens.
  2. Choose a place on the left: Home, Computer or one of the Recent projects. Or type a path in the Folder box.
  3. Open folders until you are in the one you want. A folder that holds a penstock.yaml or diagrams, decisions or forms is marked project, and the browser says which. A link to another folder is marked link. Show hidden folders lists the rest.
  4. Press Open project.

The browser lists folder names only. It never shows what is inside a file. Once a project is open, the project name in the title bar is a switcher: it lists the recent projects, Open another project… and Close project. When some open files have unsaved changes, Penstock asks first and offers Save all. The tabs of a project close when the project changes, and each project remembers what it had open.

The window

The window of Penstock Web with the diagram order-to-cash.bpmn open. The title bar is at the top. The sidebar island at the left has the Actions, the Project tree and the Chats section. The editor, with its toolbar, canvas, sidebar tabs and the AI chat at the foot, fills the rest
The window: the title bar, the sidebar with its three sections, and the editor.
Title barThe button that shows and hides the sidebar, the Penstock dot and name, the project switcher with the open file beside it (a dot marks unsaved changes), Open file (the magnifier) and Settings (the gear). The project's name is only in the title bar. The tree's own heading says Project.
SidebarOne island at the left, 272 pixels wide. Drag its edge to change the width, between 240 and 400, or focus the edge and press the arrow keys. The width and whether it is shown are remembered.
Editor groupsThe files you open, in tabs, to the right of the sidebar. See below.
Bottom stripWhether the page is connected to the server, whether the open file is saved, the engine of the project, the licence (a press opens the licence dialog), the encoding and line endings of the open file, and the shortcuts.

The sidebar

The sidebar has three sections, in this order, told apart by space and a small heading.

The border between the tree and the chats can be dragged, and moved with the up and down arrow keys. Below 900 pixels of window width the editors fill the window and the sidebar opens as a drawer over them, behind a scrim that closes it. Focus canvas, in the More menu of an editor, hides the sidebars in one go and a second press shows them again; it is never remembered.

The project tree

The tree is the same project model as in the other tools: the processes, their elements, decisions, forms, workers and the code behind them. A press on a node opens its file, or the element in it. Group by files in its toolbar turns the model round, file by file, and the filter above the list narrows it. Links to code are part of Pro, and a locked tree says so, with an Unlock button.

The project's own files are managed here, without leaving the page:

The tree rescans by itself when files change on disk.

Tabs, groups and splits

Every file you open gets a tab. Open a file from the tree, with Open file, or from the welcome area. Open file filters by name as you type, shows the files you opened lately, and takes > as the start of a command, so it is also the list of the page's commands.

The editors sit in groups of tabs, which you can split, join and resize:

The shortcuts for opening, saving, closing, switching tabs and splitting are on penstock web, and the page lists them under Keyboard shortcuts.

Saving, and changes made elsewhere

A BPMN file without a layout is laid out in memory when it opens and is written only once you edit it, so opening a file never changes it on disk.

Code, and comparing with Git

Project screens

Some screens belong to the whole project, not to one file. In Penstock Web they are in the command palette and the sidebar: Drift (environments as columns, resources as rows, a chip per state), Policy, the Migration workspace, Connections (a node of the sidebar with a finding for every problem, and an action that opens the map) and Agents. The More menu and the palette of the BPMN, DMN and form editors also have Create evidence pack… and Refactor…. See Drift, promote and protected environments, Policy pack, Camunda 7 to Camunda 8, Connections map, AI agents of Camunda 8, Evidence pack and Refactoring across the project. A .cmmn file opens in a read-only viewer (CMMN case models), and JSON files in the element template folders open in the element template editor.

Settings and the licence

Settings in the title bar has the theme (Follow the system, light, dark or Dracula), the two suggestions of the editor, autosave and Manage AI agents…, which turns the AI chat on or off, chooses where conversations open, and installs, updates and removes agents. The choices are kept in ~/.penstock/preferences.json, the same file as in the other tools.

The licence is the one of the machine, ~/.penstock/license.json. Press the licence in the bottom strip to see the plan and the days left of a trial, enter a key, buy Pro or Team (the payment page opens in a new tab) or release the machine. See Buying and signing in.

Common problems

"This page has lost its link to Penstock."
The server was restarted, and the key it printed before no longer works. Use the new link from the terminal. Your unsaved changes are still in the browser.
"The connection to the server is lost."
The server stopped or the machine slept. Unsaved changes stay in the page. Start penstock web again, and press Retry.
A split is not offered.
A group is never narrower than 480 pixels. Close the sidebar or make the window wider.
The sidebar is gone.
Below 900 pixels of width it is a drawer. Open it with the button at the left of the title bar. It can also be hidden by Focus canvas; press it again.