Pinscope on Linux

A Raspberry Pi, a gateway or any Linux device next to your microcontrollers, in the same dashboard: its web pages, logs, system metrics and updates. One command.

With an AI assistant. Copy the instructions and paste them into Claude, Cursor, Copilot or ChatGPT in your project: it adds Pinscope the way this page says, and asks you for the project key instead of writing it into your code. Or give it the link: linux.md.

# Add Pinscope to a Linux machine (Raspberry Pi, gateway)

Pinscope gives a local web interface on the machine a secure address, sends its journal, memory, load, temperature and disk to the Pinscope dashboard, and delivers update files to a command you choose. It is an agent installed as a systemd service. Full docs: https://pinscope.dev/docs/linux

## Steps

1. The project key. The user copies it from the dashboard: their project, tab **Connect a device**. Do not write it into scripts or files that are committed.
2. On the machine, with the local web port to expose as the last number (80 if unsure):
```
curl -fsSL https://pinscope.dev/install.sh | sudo sh -s psk_... 80
```
It builds the agent there (installing a compiler first on Debian, Ubuntu and Raspberry Pi OS if needed), installs the service `pinscope-agent` and prints the device's address. Running it again updates the agent or changes the key.
3. Optional, in `/etc/pinscope-agent.env`, then `sudo systemctl restart pinscope-agent`:
- `PINSCOPE_LOGS=journalctl -f -o cat -u my-service` to send a service's log;
- `PINSCOPE_UPDATE=/usr/local/bin/install-update` to take updates: the agent saves the uploaded file and runs that command with its path; exit status 0 counts as installed. Write the install command only if the user asks for updates, and show it to them.

## Check

- `systemctl status pinscope-agent` shows it running, and `journalctl -u pinscope-agent` shows `online`.
- The machine appears in the dashboard under Devices.

## Rules

- Never invent a project key and never write the user's key into a file that is committed. Ask the user for it, and keep it where the steps below say. A key is `psk_` followed by 24 letters, digits, `-` or `_`, 28 characters in all; if the one you are given is not, ask again.
- Change as little as you can: add Pinscope, do not restructure the project, rename files or touch unrelated code.
- Do not add a TLS library, certificates or port forwarding. Pinscope makes one outbound connection to `connect.pinscope.dev` on TCP port 443 and encrypts it itself.
- Do not edit Pinscope's own source; configure it.
- When you are done, tell the user exactly what you changed and what they still have to do (enter the key, flash, upload the firmware for updates).

1. Install

In the dashboard, open your project and the tab Connect a device and copy the project key. Then, on the device:

curl -fsSL https://pinscope.dev/install.sh | sudo sh -s psk_... 80

The last number is the local port to expose; 80 is the default. The installer builds the agent (installing a compiler first on Debian, Ubuntu and Raspberry Pi OS if there is none), installs it as the systemd service pinscope-agent, starts it, and prints the device's address. Run it again to update the agent or change the key; the device keeps its identity. It runs on 64-bit and 32-bit ARM and on x86-64: checked on Debian 13, Ubuntu 24.04 and 32-bit ARM.

The device appears under Devices with its host name. It needs to reach connect.pinscope.dev on TCP port 443, outbound only.

2. Reach the device

Whatever listens on the exposed port is served at the device's own HTTPS address, as for microcontrollers: a local dashboard, Node-RED, Home Assistant, a printer's page. See Reach the device. Up to four ports: PINSCOPE_PORTS=80,1880 in the settings.

3. Logs and metrics

The Logs tab shows what a command of your choice prints, for example the system journal or one service:

PINSCOPE_LOGS=journalctl -f -o cat -u my-service

Reported once a minute, with no setup:

Metric	Meaning
`heap_free`	Memory available to programs
`cpu_load`	Load over the last minute, as a share of the cores
`chip_temp_c`	SoC temperature, where the system reports one
`disk_free_mb`, `uptime_s`	Free space on the root file system, and time since boot

4. Updates

Pinscope delivers the file; a command you choose installs it. Set it in the settings:

PINSCOPE_UPDATE=/usr/local/bin/install-update

Upload any file under Firmware (a package, an archive, a script) and press Update firmware on the device. The agent saves it as /var/lib/pinscope/update.bin and runs the command with its path. An exit status of 0 counts as installed; the agent then restarts. Without PINSCOPE_UPDATE, the device takes no updates.

Settings

In /etc/pinscope-agent.env; after a change, sudo systemctl restart pinscope-agent.

Setting	What it does
`PINSCOPE_KEY`	The project key
`PINSCOPE_NAME`	The name shown in the dashboard; empty for the host name
`PINSCOPE_PORTS`	Local ports to expose, comma separated; the first is on the device's address
`PINSCOPE_VERSION`	The version shown in the dashboard
`PINSCOPE_LOGS`	A command whose output becomes the device log
`PINSCOPE_UPDATE`	A command run with the path of an uploaded file

The agent keeps its identity in /var/lib/pinscope: a random ID made on first start (the machine ID is not sent) and the credential the server gave it.

If it does not work

journalctl -u pinscope-agent -f

What you see	What to check
`credentials refused`	The key is not the one in the dashboard, or the plan's number of devices is used up
No `online at` line, no error	The device cannot reach `connect.pinscope.dev` on TCP port 443
The address shows an error page	Nothing listens on the exposed port on this device (`ss -ltn` lists what does)
An update shows an error	The update command exited with a status other than 0; its output is in the journal