Guide / Start here
Penstock Desktop
Penstock Desktop is the editor of Penstock Web in an application window of its own. It has a menu, a folder dialog, recent projects, windows that come back where you left them, and it opens .bpmn, .dmn and .form files from the file manager.
What it is
Penstock Desktop is the same editor, project tree, tabs and sidebar as Penstock Web, in a window of its own instead of a browser tab. Everything in Penstock Web applies here: the title bar, the sidebar with its actions, the Project tree and the Chats, the editor groups you split and join, saving, comparing with Git, code tabs and the settings. Read that page for the window itself. This page is about what an application adds.
Each window runs its own copy of the local server that penstock web starts, inside the application, so there is nothing to install beside it and nothing to start in a terminal. The application loads that server's page and presents its key itself, so the key is never in a link or a cookie. Nothing is sent anywhere.
Where it stands
- macOS, Linux and Windows. A disk image for macOS, an AppImage and a deb package for Linux, an installer and a zip for Windows, each for two processor families. The list is under Install it.
- A preview. It works, and it is newer than the other ways to use Penstock. Tell us what is missing in the issue tracker.
- Not signed. We have no code-signing certificate yet, so macOS and Windows show a warning the first time, and the steps below get past it. Each file has its SHA-256 in a
.sha256file beside it on the release page. - No updater. The application does not update itself. A newer build is installed over the old one.
Install it
Every build is on the latest release, with a .sha256 file beside each one. <version> is the version number. The application is free, with no time limit.
| System | Processor | File |
|---|---|---|
| macOS | Apple silicon (arm64) | Penstock-<version>-mac-arm64.dmg |
| Intel (x64) | Penstock-<version>-mac-x64.dmg | |
| Linux | x86_64 | Penstock-<version>-linux-x86_64.AppImage, Penstock-<version>-linux-amd64.deb |
| arm64 | Penstock-<version>-linux-arm64.AppImage, Penstock-<version>-linux-arm64.deb | |
| Windows | x64 | Penstock-<version>-win-x64.exe (installer), Penstock-<version>-win-x64.zip |
| arm64 | Penstock-<version>-win-arm64.exe (installer), Penstock-<version>-win-arm64.zip |
To check a download, compare the SHA-256 of the file with the one in its .sha256 file.
macOS
- Download the
.dmgfor your Mac, open it, and drag Penstock to Applications. - Open Penstock from Applications. macOS says it cannot verify the app. Press Done, not Move to Trash.
- Open System Settings, then Privacy & Security, scroll to Security, and press Open Anyway next to Penstock was blocked. Confirm with your password. This is asked once.
- Prefer a terminal?
xattr -dr com.apple.quarantine /Applications/Penstock.appdoes the same.
The icon in the Dock follows the light or dark appearance of the app. On a Mac that supports it, the system also adapts the icon in the Finder.
Linux
- AppImage. Make the file executable and run it:
chmod +x Penstock-<version>-linux-x86_64.AppImage, then./Penstock-<version>-linux-x86_64.AppImage. Use thearm64file on an arm64 machine. - deb. On Debian, Ubuntu and their relatives:
sudo apt install ./Penstock-<version>-linux-amd64.deb, or thearm64file on an arm64 machine. The package adds apenstock-desktopcommand and an entry in your application menu. Start it withpenstock-desktop,penstock-desktop <folder>orpenstock-desktop <file>.
Windows
- Download
Penstock-<version>-win-x64.exe, or thearm64one on an arm64 PC, and run it. The installer lets you choose the folder. - Windows SmartScreen says it protected your PC, because the installer is not signed. Press More info, then Run anyway.
- Prefer no installer? Unpack the
.zipinto a folder of your own and start Penstock from it. SmartScreen asks the same question the first time.
Updating is the same again on every system: download the newer build and install it over the old one. Your projects and settings stay where they are.
Open a project
- Start the application. The first window offers Open a project: Choose a folder with BPMN diagrams, DMN decisions and forms. with an Open project… button and the recent projects under it.
- Press Open project… and choose a folder in the system's own folder dialog. Or pick a recent project.
- The window shows the name of the project with Opening… while its server starts, then shows the editor.
A project opens in the window you are in when that window has no project. Otherwise it opens in a window of its own. Opening the same project twice brings its window to the front.
From the file manager, and from a terminal
- Double-click a
.bpmn,.dmnor.formfile, or choose Penstock in Open With or the equivalent of your system. The application registers for these three kinds of file. The project it opens is the nearest folder above the file that holds apenstock.yamlor a.git, and the file opens in it. Without either, the file's own folder is the project. - Give the application a folder or a file on its command line, which on Linux is
penstock-desktopafter a deb install.--new-window, or-n, opens a window of its own. - There is one application at a time. Starting it again hands the request to the one that is running, and brings its window forward.
Windows
- A window for each project. New window opens an empty one. Close project returns a window to the welcome screen.
- They come back. The application remembers its open windows with their position and size, whether they were maximised or full screen, their project and their zoom, and brings them back at the next start. A window that would land off the screen is moved back onto it. A window is never smaller than 720 by 480 pixels.
- Zoom. Zoom in, Zoom out and Actual size in the View menu, remembered for each project.
- Recent projects. Open recent in the File menu lists the last ten, and Clear recent projects empties the list. On macOS, the Dock menu has New window and the five latest.
- Closing with unsaved changes. A window with unsaved files asks Close without saving? with Discard changes and Cancel. Quitting asks the same for every window that has them.
The menu
| File | New file, New window, Open project…, Open recent, Close project, Save, Reveal in Finder, Show in Explorer or Show in file manager (the open file), Close tab. |
| Edit | Undo, Redo, Cut, Copy, Paste and Select all elements, for the open file. Cut, copy, paste and select all in a diagram work across tabs and windows. |
| View | Toggle project tree, Toggle sidebar (the sidebar of the editor), the three zoom commands and full screen. |
| Window | The system's own window commands. |
| Help | Keyboard shortcuts and Penstock website. The application menu has About Penstock. |
The menu shows the shortcut of each command. The keys for tabs, splits, opening a file and the rest are the ones of Penstock Web, listed under Keyboard shortcuts. New file has the usual key for a new document here, not the one of the browser version.
What it shares with your other tools
- The licence.
~/.penstock/license.json, the same file as the command line, the plugin and the extension. A licence bought or entered in one is in the other. See Buying and signing in. - Your preferences.
~/.penstock/preferences.json, with the theme, the width of the sidebar, autosave, the AI chat and the agents. See Files Penstock reads and writes. - The project.
penstock.yamland the profiles, read from the project folder as everywhere.
The application keeps two things of its own: the position of its windows and the list of recent projects. They are in the application's data folder, not in ~/.penstock. The theme is chosen in Settings, as in Penstock Web.
When something goes wrong
- "The editor engine stopped".
- The server of that window ended. A server that ends by itself is started again once, after a second, on the same port, so the open page keeps its unsaved changes and carries on without a message. If the new one cannot start, or stops again, the window shows this screen and waits. Your unsaved changes are still in the window. Press Restart. A project that cannot run never loops.
- "Unable to start the editor".
- The server did not start for that project. Details shows the reason. Press Restart, or Open another project… to choose a different folder.
- "The editor window stopped".
- The window itself failed. Press Reload.
- A link in the editor opens in a browser.
- Links to web pages,
http,httpsandmailtoonly, open in your own browser. The window shows only its own editor.