Penstock

Command line / Start here

penstock web

penstock web serves the Penstock editors in a browser tab on your own machine, for the folder you give it. It listens on 127.0.0.1 behind a key that is different on every run, so only the page it opens can talk to it.

Free Node.js 22.22.2 or later in 22, 24.15.0 or later in 24, or 26 and later. What needs Pro in an editor needs Pro here too.

Start it

penstock web ./processes
penstock web
penstock web ./processes --port 9000 --no-open
  1. Run penstock web [folder]. With a folder it opens that project. Without one it starts on a welcome page where you choose the project in the browser, and the recent ones are one click away.
  2. The command prints what it serves, the link, and how to stop it:
    Serving /home/me/processes
      http://127.0.0.1:8765/?token=...
    Press Ctrl+C to stop.
    With no folder the first line is No project is open yet. Choose one in the browser.
  3. A browser opens on the link by itself. With --no-open you open the link yourself.
  4. Work in the page. See Penstock Web for the window.
  5. Press Ctrl+C in the terminal to stop the server. It says Stopping. and exits with 0. A second press leaves at once.

The server starts on port 8765. When that port is busy it tries the next one, up to 99 higher, and says Port 8765 is in use, so Penstock uses 8766. If none of them is free it stops with No port from 8765 to 8864 is free.

Options

OptionWhat it does
--port <port>The port to listen on, 8765 by default. The next free one is used when it is busy. 0 takes any free port. The value should be a number from 0 to 65535.
--host <address>The address to listen on, 127.0.0.1 by default. Any other makes the folder reachable from the network, and the command prints a warning. See Who can reach it.
--no-openPrint the link and do not open a browser.
--profile <name>Use this profile, as PENSTOCK_PROFILE would.

The folder you give should exist and be a folder. The command refuses a filesystem root or a home folder that holds no penstock.yaml and no .git. It says This folder is too large to be a project; give the folder of the diagrams. See Every command for the exit codes.

Who can reach it

The server is made for one person on one machine, and nothing is sent anywhere.

A link never picks a folder. A project is opened by the folder argument or by the folder browser, which lists folder names only, never a file's contents. Opening, closing or switching a project moves everything with it: a request made for the previous project is answered with an error instead of being served from the wrong folder, and a switch is refused while a deploy runs.

What it remembers

Your choices live in ~/.penstock/preferences.json, the file the other tools use, or under PENSTOCK_HOME when that is set. It is readable by its owner only.

recentProjectsThe projects on the welcome page and in the project switcher.
webSessionsWhat was open, one entry for each project folder: the tabs, the groups and how they are split, and the tree.
projectTreeWidth, projectTreeHiddenThe width of the sidebar, between 240 and 400 pixels, and whether it is shown.
webAutosaveSecondsThe seconds without an edit after which a file is written. Absent means no autosave.
themeFollow the system, light, dark or Dracula.
suggestNextBlock, suggestionsWhether the editor suggests the next element and names, sources and expressions. Both are on unless set to false.
showCodeBadgesWhether the small marks that say whether the code behind a task was found are drawn.
aiChatoff, bottom or sidebar: where the AI chat is.
languageServersYour own language servers. See below.

Code in the page

A class or a bean that a diagram names opens in a read-only code tab. Code tabs and the XML text of a file are highlighted for Java, Kotlin, Scala, C#, Python, Go, Groovy, JavaScript, TypeScript, JSON, YAML, XML, SQL, Markdown and properties files, in the colours of the editor's theme.

For completion, hover, diagnostics and go to definition, the page talks to a language server that is installed on the machine that runs penstock web. Penstock looks for these on the PATH:

LanguageCommand
Javajdtls
Kotlinkotlin-language-server
TypeScript and JavaScripttypescript-language-server --stdio
JSONvscode-json-language-server --stdio, or vscode-json-languageserver --stdio
YAMLyaml-language-server --stdio
XMLlemminx
Markdownmarksman server
Pythonpyright-langserver --stdio
Gogopls

Without a server the tab still highlights, and says Highlighting only. Install the server to get completion, hover and go to definition here. with the name of the server. To use another server, or another command line, add it under languageServers in ~/.penstock/preferences.json. An entry of yours with the same id as a preset replaces the preset.

{
  "languageServers": [
    {
      "id": "my-java",
      "languages": ["java"],
      "command": "/opt/jdtls/bin/jdtls",
      "args": ["-data", "/tmp/jdtls-workspace"],
      "env": { "JAVA_HOME": "/opt/jdk" }
    }
  ]
}

A line of code that a diagram element names, such as a job type, a topic, a class, a bean or a message, gets a marker beside its line number and a hover that names the diagram and the element. A click opens the diagram on that element. In the XML text of a file, completion offers the job types, topics, classes, beans and message names that the project shares with its code. Links between diagrams and code are part of Pro, as in every tool.

Keyboard shortcuts

The page binds these keys. Press Ctrl+/ (Cmd+/ on a Mac) in the page to see them, or choose Keyboard shortcuts from the command list. The editors have their own keys. Press ? inside an editor to see them.

ActionWindows and LinuxmacOS
Open fileCtrl+PCmd+P
Find actionCtrl+Shift+PCmd+Shift+P
New fileCtrl+Alt+NCmd+Alt+N
SaveCtrl+SCmd+S
Save allCtrl+Shift+SCmd+Shift+S
Close tabCtrl+W or Ctrl+Alt+WCmd+W or Cmd+Alt+W
Next and previous tabCtrl+Tab, Ctrl+Shift+Tab, Ctrl+Alt+PageDown, Ctrl+Alt+PageUpCtrl+Tab, Ctrl+Shift+Tab, Cmd+Alt+PageDown, Cmd+Alt+PageUp
Jump to tab 1 to 9, the last for 9Ctrl+1 to Ctrl+9Cmd+1 to Cmd+9
Split view, or close the splitCtrl+\Cmd+\
Show or hide the sidebarCtrl+BCmd+B
Ask the agent, when the AI chat is onCtrl+Alt+ACmd+Alt+A
Keyboard shortcutsCtrl+/Cmd+/

Focus canvas hides the sidebars so the canvas has the whole window. It is in the More menu of an editor, with the shortcut Ctrl+Alt+Shift+M (Cmd+Alt+Shift+M on a Mac). A second press shows them again. It is not remembered.

Common problems

"This page has lost its link to Penstock."
The key belongs to one run. After penstock web was restarted, use the link it printed in the terminal. Unsaved changes stay in the browser and come back when you open the project again.
"The port should be a number from 0 to 65535".
Give --port a whole number, or leave it out.
"The address should be an IP address or a host name".
Check --host. Leave it out to listen on this machine only.
"The editor page is not part of this build, so only the API answers."
The installation lacks the editor page. Install the command line again with npm install -g @kern0x1b/penstock-cli. Setting PENSTOCK_WEB_ROOT to a built page serves that page instead.
"Penstock is unable to open a browser."
Open the link above the message yourself.
"The server is serving another project now."
The project was changed in another tab. Reload the page to follow it.
"Running tests from code needs an IDE."
The page does not run the tests of a worker. Run penstock scenarios run in a terminal. See scenarios run.