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.
Start it
penstock web ./processes
penstock web
penstock web ./processes --port 9000 --no-open
- 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. - The command prints what it serves, the link, and how to stop it:
With no folder the first line is No project is open yet. Choose one in the browser.Serving /home/me/processes http://127.0.0.1:8765/?token=... Press Ctrl+C to stop. - A browser opens on the link by itself. With
--no-openyou open the link yourself. - Work in the page. See Penstock Web for the window.
- 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
| Option | What 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-open | Print 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.
- Only this machine. It listens on 127.0.0.1. With
--hostset to an address that is not the machine's own loopback, anyone who can reach the machine and holds the link can read and change the diagrams of the open project, and see folder names on the machine. The command prints that warning. - A key on every request. Every request needs the key of this run. The link carries it once. The page that answers the link keeps it in a cookie the page's own scripts cannot read, then reloads without it. When the browser is opened by the command, the link holds a code that works once and expires after a minute, so the key is not in the process list. The key is never logged.
- Only its own page. A request whose
Hostis not the server's own, or that comes from another web page, is refused before anything else. - Only the project folder. Paths are resolved inside the folder, and anything that leaves it, contains
..or points into.gitis refused. The server writes only diagrams, decisions, forms, test cases, element templates andpenstock.yaml. - Bounded. A request has two minutes, bodies are limited to 1 MB (24 MB for a file), and a file over 64 MB is not read.
- Hooks need trust. The deployment hooks of
penstock.yamlrun only in a project thatpenstock trustknows. Passwords are kept in memory for the run.
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.
recentProjects | The projects on the welcome page and in the project switcher. |
webSessions | What was open, one entry for each project folder: the tabs, the groups and how they are split, and the tree. |
projectTreeWidth, projectTreeHidden | The width of the sidebar, between 240 and 400 pixels, and whether it is shown. |
webAutosaveSeconds | The seconds without an edit after which a file is written. Absent means no autosave. |
theme | Follow the system, light, dark or Dracula. |
suggestNextBlock, suggestions | Whether the editor suggests the next element and names, sources and expressions. Both are on unless set to false. |
showCodeBadges | Whether the small marks that say whether the code behind a task was found are drawn. |
aiChat | off, bottom or sidebar: where the AI chat is. |
languageServers | Your 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:
| Language | Command |
|---|---|
| Java | jdtls |
| Kotlin | kotlin-language-server |
| TypeScript and JavaScript | typescript-language-server --stdio |
| JSON | vscode-json-language-server --stdio, or vscode-json-languageserver --stdio |
| YAML | yaml-language-server --stdio |
| XML | lemminx |
| Markdown | marksman server |
| Python | pyright-langserver --stdio |
| Go | gopls |
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.
| Action | Windows and Linux | macOS |
|---|---|---|
| Open file | Ctrl+P | Cmd+P |
| Find action | Ctrl+Shift+P | Cmd+Shift+P |
| New file | Ctrl+Alt+N | Cmd+Alt+N |
| Save | Ctrl+S | Cmd+S |
| Save all | Ctrl+Shift+S | Cmd+Shift+S |
| Close tab | Ctrl+W or Ctrl+Alt+W | Cmd+W or Cmd+Alt+W |
| Next and previous tab | Ctrl+Tab, Ctrl+Shift+Tab, Ctrl+Alt+PageDown, Ctrl+Alt+PageUp | Ctrl+Tab, Ctrl+Shift+Tab, Cmd+Alt+PageDown, Cmd+Alt+PageUp |
| Jump to tab 1 to 9, the last for 9 | Ctrl+1 to Ctrl+9 | Cmd+1 to Cmd+9 |
| Split view, or close the split | Ctrl+\ | Cmd+\ |
| Show or hide the sidebar | Ctrl+B | Cmd+B |
| Ask the agent, when the AI chat is on | Ctrl+Alt+A | Cmd+Alt+A |
| Keyboard shortcuts | Ctrl+/ | 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 webwas 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
--porta 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. SettingPENSTOCK_WEB_ROOTto 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 runin a terminal. See scenarios run.