Pi Bay: manage Raspberry Pis and SSH devices

What it is

A local workspace for Raspberry Pis and other SSH devices on your LAN. Open the browser, find your devices, sign in over SSH, and work with their files and a terminal. It also recognizes ctrlPi agents, including Picos and ESP32s, and shows their ctrlPi version.

Quick start

Requires Node.js 20 or newer and SSH enabled on the target device:

npx @ctrlpi/pi-bay

Your browser will open automatically! If it doesn't, head to http://localhost:8383.

Your devices, in the browser

Feature	What it does
Devices	Find Raspberry Pis and other SSH devices on your network as the scan runs, detect ctrlPi agents (Picos and ESP32s too), and see each device's name, IP and MAC address, model, and ctrlPi version.
Sign in	Sign in over SSH. Passwords can be saved in the system keychain, and SSH keys work too.
Files	Browse the home folder over SFTP as a searchable tree. Create, rename, move, upload, download, and recursively delete files and folders, edit text files in the browser, format JSON, and preview Markdown. Drag and drop files and whole folders.
Run & terminal	Run `.py`, `.sh`, `.bash`, and `.js` files on the device from their own folder, or open an interactive SSH shell in full color that stays open while you switch to Files.
Backups	Download and restore the home folder as a standard ZIP archive.
ctrlPi API	Install or update pi-gpio-api on a Pi from the menu.
Power	Reboot a Pi from the menu, or toggle its USB power with `uhubctl`.

Install the ctrlPi API

Choose Install ctrlPi API in the top-right menu to install pi-gpio-api on the connected Pi. A popup asks for the agent name, the API key, and the Lite (recommended) or Full package. pi-bay writes ~/pi-gpio-api/config.json with the name and key, then runs the installer in the Terminal tab so you can follow it.

If the Pi already has that config.json, its agent name and API key are kept and the installer updates pi-gpio-api in place. The installer ends with the sudo commands that create and start the pi-gpio-api service, or restart it; run them in the same terminal. The pi_ctrlpi_install MCP tool does the same without the terminal.

Signing in

Only pi_device_authenticate takes a username and password. Everything else reuses its connection, or signs in again by itself with a password saved in the macOS Keychain or Linux Secret Service, or with your SSH keys (the SSH agent and the default identity files).

Connect an MCP client

pi-bay includes a dependency-free MCP server, enabled by default on Raspberry Pi hosts. On macOS and other hosts, enable it in the app or pass --mcp-stdio or --mcp-http. Stdio mode runs only the MCP transport, without a web server or browser.

For an MCP client that launches local servers, add this entry to its MCP configuration:

{
  "mcpServers": {
    "pi-bay": {
      "command": "npx",
      "args": ["-y", "@ctrlpi/pi-bay", "--mcp-stdio"]
    }
  }
}

pi-bay has 12 MCP tools for devices, files, commands and the ctrlPi API. See the README for the full list.

For Streamable HTTP, start the server with:

npx @ctrlpi/pi-bay --mcp-http

MCP is available at http://localhost:8383/mcp, alongside the web interface. Raspberry Pi hosts enable HTTP MCP and listen on the LAN by default. Other hosts listen locally unless you explicitly set --host 0.0.0.0.

No authentication or TLS. MCP tools can run shell commands, overwrite and delete files, install software, and reboot devices. HTTP mode is for a trusted local network only: do not expose /mcp or pi-bay's port to the internet.

In the family

Use pi-bay to reach a Raspberry Pi over SSH: its files, a terminal, and a one-step install of pi-gpio-api. pico-bay does the same for Pico and ESP32 boards over USB. Once an agent is running, ctrlpi-cli and ctrlpi-lab control GPIO over the network.

mcp-bridge exposes those network agents to AI clients, while pi-bay's own MCP tools work directly with your Pis. To put the same pins in Apple Home, use homebridge-ctrlpi.