What runs where

Pinrail sits between your agents and the things they do, so it matters what it can reach. This page lists what runs where, and what each part is allowed to do.

Everything is on your machine

Click to enlarge

The parts, and the boundaries between them

• The server listens on your machine’s loopback address, 127.0.0.1, port 4747 by default. Programs on your computer can reach it, but nothing on the network can. Web pages you visit cannot reach it either. It answers only requests addressed to 127.0.0.1 or localhost. It changes nothing unless the request is JSON, and browsers do not let another site send JSON to it.
• Reviews and decisions are stored in your data directory, ~/.local/share/pinrail by default, with the files sent beside reviews. Pinrail makes that directory readable only by your user account, so other users of the computer cannot read your reviews. There is no account and no cloud service.
• The app shows reviews and sends your decisions. Nothing leaves your machine unless an agent, acting on your decision, sends it.

What a plugin’s view can do

A plugin’s view is a page the app shows inside a sandboxed frame. However the plugin was installed, the view:

• can draw, and exchange messages with the app;
• can ask the app to open a link in your browser or mail client. The app asks you first, showing the site, unless you allowed that site for this plugin. It never opens an address on your own computer, and it always asks about an email or a very long address;
• cannot use the network, so it cannot make requests or load web fonts, scripts or styles from elsewhere;
• cannot store data, and can read only what the app sends it. When the view asks for one of its review’s attachments by name, the app sends it, but the view cannot read another review’s attachments;
• cannot see other reviews, other plugins, or your files.

Everything a view shows arrives in the review’s payload or in its attachments. That is why a code review sends the diff rather than a link to it.

Attachments are only displayed inside a view’s sandbox, whatever they contain. The view asks the app for an attachment’s contents and displays it itself. The artifact plugin, for example, displays an attached HTML page this way. The app itself never opens an attachment. It lists each one by name and size, and saving one writes its contents to disk unchanged.

What installing a plugin runs

Installing a plugin runs nothing. Pinrail installs a plugin from a folder or a zip on your computer: it copies the plugin’s static files into its store and checks them, and it downloads nothing. A plugin whose view is made with a build tool is built before it is installed, by its author or by you.

Building a plugin runs code

If you build a plugin yourself, for example with npm ci && npm run build, that build runs on your machine as you: npm ci runs the install scripts of every package in the dependency tree, and the build runs whatever the plugin’s package says. Plugins and their zips are not signed, and plugin authors are not vetted, so install plugins only from people whose code you would run.

After installation, a plugin consists only of static files, and its view runs in the same sandbox as any other.

What the agent can do

Pinrail does not run your agents or limit what they do. It gives them a way to ask, and it reports your answer faithfully. Whether an agent asks, and whether it respects the answer, is up to its instructions and its harness. Write instructions that name the moments to ask, and prefer tools that enforce them. See Instructing an agent.