Do I need a cloud account or subscription?
No. The entire ctrlPi ecosystem is designed to run locally on your own network. There are no external cloud dependencies, no subscriptions, and your data never leaves your LAN.
Which hardware models are supported?
Our agents support the Raspberry Pi A+, B+, 2, 3, 4, 5, Zero W, and Zero 2 W running Raspberry Pi OS (pi-gpio-api), the Raspberry Pi Pico W and Pico 2 W in MicroPython (pico-gpio-api), and ESP32, ESP32-C3, and ESP32-S3 boards in MicroPython (esp32-gpio-api).
How does Pico Bay relate to ctrlPi?
Pico Bay is a standalone desktop/web app in the ctrlPi family. While the main ctrlPi agents run on the Pi over Wi-Fi, Pico Bay runs on your computer to manage Pico and ESP32 boards over a physical USB connection (for firmware flashing, file management, and MCP access).
Is ctrlPi open source?
Yes, all ctrlPi projects, agents, bridges, and tools are completely open-source under the MIT license. You can find all the code on our GitHub organization.
How do I connect ctrlPi to Apple HomeKit?
Use the homebridge-ctrlpi plugin. Add it to your Homebridge server and it exposes your pi-gpio-api, pico-gpio-api, and esp32-gpio-api devices to Apple Home, configured from the Homebridge UI.
Can I use ctrlPi with Homebridge?
Yes. If you already run a Homebridge server, you can use the homebridge-ctrlpi plugin to expose your ctrlPi agents.
Does ctrlPi support Matter?
Not yet. Matter support is coming with matter-bridge, which will bring your Pi, Pico, and ESP32 agents into Apple Home, Google Home, Amazon Alexa, and other Matter ecosystems. Until then, Apple Home works through the homebridge-ctrlpi plugin.
How do I configure my devices?
Your agents are listed in ~/.ctrlpi/agents-config.json, a single shared file that every ctrlPi tool reads. Discovery fills it in for you, so you rarely edit it by hand. Pins, names, and sensors are set on each agent through its REST API, ctrlpi-lab, or ctrlpi-cli, and the Homebridge settings form names each device.
Is there a graphical interface for managing my devices?
Yes. You can run the ctrlpi-lab web app on your computer to monitor and control all the ctrlPi agents it finds on your network. From one page you can test every endpoint, tail an agent's logs, and watch webhook events, without writing any requests by hand.
How does the AI integration work?
The mcp-bridge implements the open Model Context Protocol (MCP). It allows AI assistants like Claude Desktop to securely interact with your local devices. The AI uses the MCP server to dynamically discover what hardware you have and control it directly.
How do I configure MCP with stdio?
In stdio mode, your MCP client (such as Claude Desktop or Claude Code) launches the server directly as a local subprocess. Add it to your claude_desktop_config.json under mcpServers:
{
"mcpServers": {
"ctrlpi": {
"command": "npx",
"args": ["-y", "@ctrlpi/mcp-bridge"]
}
}
}For USB microcontroller boards using Pico Bay, specify ["-y", "@ctrlpi/pico-bay", "--mcp-stdio"]. The client automatically runs and stops the process over stdin/stdout with no background daemon needed.
How do I configure MCP with HTTP?
In HTTP mode, the MCP server runs continuously in the background - ideal for a Raspberry Pi on your network. Start the server with HTTP mode enabled:
npx -y @ctrlpi/mcp-bridge --http
The bridge listens on port 8315 at http://<host>:8315/mcp (or port 7426 for Pico Bay with --mcp-http). In Claude Desktop, connect via mcp-remote passing your API key, or connect Claude Code directly using the HTTP transport:
claude mcp add ctrlpi --transport http http://<host>:8315/mcp --header "Api-Key: your-mcp-key"
Are webhooks supported for sensors and buttons?
Yes. The Pi, Pico, and ESP32 agents support real-time HTTP webhooks. You can configure them to send an instant POST request to any local URL (like Node-RED or Home Assistant) whenever a button is pressed or a sensor changes state.