Protoboard Installation guide

← Downloads For an agent: the same guide as plain text is at /guide.md

Installing Protoboard

Protoboard designs hardware as code. A project is a folder: its modules, the interfaces between them and the cables that connect them are written in UHD, and the protoboard command checks them, builds them and makes a release. The Protoboard extension shows the project as a diagram and in 3D in VS Code, Cursor or Windsurf. An AI coding agent does most of the writing; you watch the result in the editor.

This guide is for a person and for an agent doing the work for a person. The steps are the same. Where an agent has to ask its user something, a note says so.

The current version. This guide names no version number on purpose: you always install the current version. To see which one you have, run protoboard --version in a terminal, or Protoboard: Open Settings in the editor. The extension and the command line share one version number and move together.

If you are an agent doing this for someone: ask them these questions before you install anything, in plain words, and wait for the answers. Do not choose for them.

  1. Which editor? VS Code, Cursor or Windsurf.
  2. Which agent? Claude Code, Codex, Cursor's agent, Windsurf's agent, GitHub Copilot in VS Code, or another MCP client. You may be the answer.
  3. Start a project now? If yes, in which folder, under what name, and from which starting point (Your first project).

What you need

Needed forNotes
VS Code, Cursor or Windsurfthe extension: the viewer, the Inspector, the checks in the editorA current release. The extension needs an editor built on VS Code 1.106 or later; an older one refuses to install it and says so.
Nothing elsethe extension and the protoboard command it bringsThe extension carries the whole stack and runs it with the editor's own runtime: no Node.js, no npm.
Node.js 22 or later, with npmthe command line from npm; boards (the circuit runtime)Only if you install the command line with npm, or design circuit boards.
Python 3, from 3.11 to 3.14the 3D generators: enclosures, frames, cables and part bodiesOnly for CAD. protoboard tools install cad makes a Python runtime of about 1 GB for a project, once.
Google Chrome, Chromium, Microsoft Edge or Bravedocuments and the release package's PDFsFound where your system installs it, or set CHROME to its executable.
KiCad 10the hand-placement step of a board, and its fabrication outputsOptional.
An accountthe Protoboard library onlyLocal work needs no account. See Signing in for the library.
An AI coding agentwriting the project with youOptional, and what Protoboard is built for. See Connect your agent.

Install on macOS

The extension

In VS Code, open the Extensions view (Cmd+Shift+X), search for Protoboard and press Install. It is published by Delta Robotics, on the Visual Studio Marketplace for VS Code and on Open VSX for Cursor and Windsurf. Cursor and Windsurf show Open VSX in their own Extensions view: search for Protoboard there. From a terminal:

code --install-extension deltarobotics.vscode-protoboard

(cursor or windsurf in place of code for those editors.) The terminal knows code only after Shell Command: Install 'code' command in PATH from VS Code's command palette (Cmd+Shift+P). Until then it is /Applications/Visual Studio Code.app/Contents/Resources/app/bin/code.

The first time it starts, the extension unpacks Protoboard into ~/.protoboard and shows its progress: some seconds, once per version. Then the Protoboard icons are in the side bar and Sign in is in the status bar.

The protoboard command

New terminals inside the editor have the protoboard command already. For every other terminal, and for an agent that starts its own shell, run Protoboard: Add the protoboard Command to PATH once from the command palette. It adds one line, marked protoboard-path, to the end of your shell's start file (~/.zshrc for zsh, ~/.bash_profile for bash) and says which. Open a new terminal afterwards. The command itself is ~/.protoboard/bin/protoboard.

Or install the command line with npm instead (Node.js 22 or later):

npm i -g @protoboardai/cli

npm puts it on your PATH itself. The extension and an npm install work side by side.

Check it

protoboard --version
protoboard doctor

doctor lists the version and build, your sign-in, where the stack's packages come from and, in a project, its extensions, tools and skills (what each line means: Troubleshooting).

The 3D generators need a Python that can make a runtime. Homebrew's cannot on some macOS versions: protoboard tools install cad then lists what it tried and prints what to run instead (brew install uv && uv python install 3.12, then protoboard tools install cad again).

Install on Windows

The extension

In VS Code, open the Extensions view (Ctrl+Shift+X), search for Protoboard and press Install: the one published by Delta Robotics. In Cursor or Windsurf, the same in their own Extensions view (they install from Open VSX). From PowerShell:

code --install-extension deltarobotics.vscode-protoboard

The VS Code installer adds code to PATH (its option "Add to PATH", on by default): open a new terminal after installing VS Code. Otherwise it is "%LOCALAPPDATA%\Programs\Microsoft VS Code\bin\code.cmd" (installed for you alone) or "%ProgramFiles%\Microsoft VS Code\bin\code.cmd" (for everyone).

The first time it starts, the extension unpacks Protoboard into %USERPROFILE%\.protoboard and shows its progress. SmartScreen or your antivirus may ask about the editor the first time; that is not Protoboard.

The protoboard command

New terminals inside the editor have the protoboard command already. For every other terminal, run Protoboard: Add the protoboard Command to PATH once from the command palette (Ctrl+Shift+P). It adds %USERPROFILE%\.protoboard\bin to the end of your user Path (your own environment variables; no administrator rights). Open a new terminal afterwards. The command itself is %USERPROFILE%\.protoboard\bin\protoboard.cmd.

Or install the command line with npm (Node.js 22 or later):

npm i -g @protoboardai/cli

Commands in this guide work as written in PowerShell and in the editor's terminal. In the old Command Prompt, put a link that contains & in double quotes.

Check it

protoboard --version
protoboard doctor

The 3D generators need Python from python.org or the Microsoft Store; open a new terminal after installing it.

Install on Linux

The extension

In VS Code, open the Extensions view (Ctrl+Shift+X), search for Protoboard and press Install: the one published by Delta Robotics. In Cursor, Windsurf or VSCodium, the same: they install from Open VSX. From a terminal:

code --install-extension deltarobotics.vscode-protoboard

VS Code's .deb, .rpm and snap packages install code on your PATH. The extension carries Protoboard for x64 and arm64 Linux with glibc; on a system with musl (Alpine) install the command line with npm instead.

The first time it starts, the extension unpacks Protoboard into ~/.protoboard and shows its progress.

The protoboard command

New terminals inside the editor have the protoboard command already. For every other terminal, run Protoboard: Add the protoboard Command to PATH once from the command palette (Ctrl+Shift+P). It adds one line, marked protoboard-path, to the end of your shell's start file (~/.bashrc, ~/.zshrc, a fish conf.d file, else ~/.profile). Open a new terminal afterwards. The command itself is ~/.protoboard/bin/protoboard.

Or install the command line with npm (Node.js 22 or later):

npm i -g @protoboardai/cli

Check it

protoboard --version
protoboard doctor

The 3D generators need python3 with venv (on Debian and Ubuntu: sudo apt install python3-venv). The document checks use poppler (sudo apt install poppler-utils).

If you are an agent doing this for someone: installing an extension and changing a shell's start file are their decisions. Ask before you run code --install-extension or npm i -g, and say what each changes. Never run a bare npx protoboard: npm would fetch an unrelated public package of that name. The scoped name is npx @protoboardai/cli.

Setting up a machine from the command line

protoboard setup installs the extension into every editor it finds (VS Code, Cursor, Windsurf and VSCodium, asking about each), then offers to put the protoboard command on your PATH and to connect your agents. It needs no account and no sign-in. It never runs by itself, and it is safe to run again.

protoboard setup

It installs the extension by its id, deltarobotics.vscode-protoboard, through each editor's own command (code --install-extension deltarobotics.vscode-protoboard, and the same with cursor, windsurf or codium): VS Code takes it from the Marketplace, the others from Open VSX. If an editor answers that the extension is not there, setup says so in one line and still sets up the PATH and your agents. On a machine without a connection, give it the .vsix file instead:

protoboard setup --vsix <file>
ToAdd
Set up one editor only (code, cursor, windsurf or codium)--editor <id>
Not be asked about each editor and the PATH--yes
Leave the agents' configuration alone--no-agents

Connect your agent

A connected agent has Protoboard's MCP server, protoboard-stack: it knows what Protoboard is in any folder, an empty one included, and has Protoboard's commands as tools (project_status, project_init, project_check, project_inspect, project_build, parts_search, parts_add, skill_read, bom, release_check and others). Connect it in one of three ways:

protoboard agents setup
protoboard agents

Each way changes only Protoboard's entry in the agent's configuration file, keeps a copy of the file before its first change (<file>.protoboard-backup), and says what it wrote where. A file that does not parse is left alone. Another server named protoboard (an older Protoboard product's) is left as it is.

The entry starts a small launcher in Protoboard's own folder, so it keeps working when Protoboard updates:

The launcher
macOS and Linux~/.config/protoboard/agents/protoboard-mcp (in $XDG_CONFIG_HOME/protoboard when that is set)
Windowscmd /c %APPDATA%\protoboard\agents\protoboard-mcp.cmd

The launcher is written with the first connection. For a client you set up by hand, run protoboard agents refresh once to write it.

What the agent reads. Every project has an AGENTS.md: what Protoboard is, the order of work, the rules and the list of skills. Its CLAUDE.md holds one line, @AGENTS.md, so Claude Code reads the same. The skills (step-by-step guides for each stage) are copied to .claude/skills/ for Claude Code; any agent reads one with protoboard skills read <name> or the skill_read tool. The MCP server tells every agent it connects to to call project_status first, then to read AGENTS.md and the build-a-project skill.

If you are an agent doing this for someone: an agent's configuration is theirs. Ask which agents to connect, then run protoboard agents setup --agent <id> --yes for each one they named (the ids are in protoboard agents --format json). Without a terminal to ask at, agents setup changes nothing unless it is given --agent or --all with --yes.

Claude Code

Connect: Connect on the Claude Code row, or protoboard agents setup. Protoboard runs Claude Code's own command for this, because Claude Code rewrites its configuration file while it runs. By hand, on macOS or Linux:

claude mcp add --scope user protoboard-stack -- ~/.config/protoboard/agents/protoboard-mcp

On Windows, copy the line protoboard agents config prints. In Claude Code, /mcp lists the server once a new session starts.

Reads: CLAUDE.md (which imports AGENTS.md) and the skills in .claude/skills/.

First prompt, in an empty folder:

Use the protoboard-stack tools. Call project_status, then make me a Protoboard project here from the iot template and run a check. Tell me what is in it before you change anything.

Codex

Connect: Connect on the Codex row, or protoboard agents setup. It adds the server to ~/.codex/config.toml (in $CODEX_HOME when that is set), which the Codex CLI, its IDE extension and its desktop app share. By hand, with your home folder's full path:

[mcp_servers.protoboard-stack]
command = "/Users/you/.config/protoboard/agents/protoboard-mcp"
args = []

Reads: AGENTS.md; the skills through protoboard skills read <name>.

First prompt, in a project:

Read AGENTS.md and the build-a-project skill. Then run protoboard check and tell me what the project is and what it reports.

Cursor

Install the extension from Cursor's Extensions view (Open VSX). Connect: Connect on the Cursor row in Protoboard: Open Settings, or protoboard agents setup. It adds the server to ~/.cursor/mcp.json; Cursor lists it under Settings, MCP: turn it on there if it is off. By hand:

{
  "mcpServers": {
    "protoboard-stack": {
      "type": "stdio",
      "command": "/Users/you/.config/protoboard/agents/protoboard-mcp",
      "args": []
    }
  }
}

Reads: AGENTS.md, and the skills through the skill_read tool.

First prompt, in Cursor's agent:

Use the protoboard-stack tools: call project_status, read AGENTS.md, then give me a rough draft of a smart water bottle cap that measures the water level and shows it on LEDs. Ask me your questions first.

Windsurf

Install the extension from Windsurf's Extensions view (Open VSX). Connect: Connect on the Windsurf row, or protoboard agents setup. It adds the server to ~/.config/devin/mcp_config.json (%APPDATA%\devin\mcp_config.json on Windows), or to ~/.codeium/windsurf/mcp_config.json when that is the file this machine has. Refresh the MCP servers in Cascade's settings, or restart Windsurf. By hand, the same mcpServers JSON as for Cursor, without the type line.

Reads: AGENTS.md, and the skills through the skill_read tool.

First prompt, in Cascade:

Call project_status from the protoboard-stack server, then read AGENTS.md and tell me how to start a Protoboard project in this folder.

GitHub Copilot agent mode

Connect: Connect on the VS Code (Copilot agent mode) row, or protoboard agents setup. It adds the server to VS Code's own user mcp.json (~/Library/Application Support/Code/User/mcp.json on macOS, %APPDATA%\Code\User\mcp.json on Windows, ~/.config/Code/User/mcp.json on Linux; VS Code Insiders has its own). The server starts the next time agent mode lists its tools. By hand, in that file:

{
  "servers": {
    "protoboard-stack": {
      "type": "stdio",
      "command": "/Users/you/.config/protoboard/agents/protoboard-mcp",
      "args": []
    }
  }
}

Reads: AGENTS.md, and the skills through the skill_read tool.

First prompt, in Copilot Chat with the agent selected:

Use the protoboard-stack tools. Call project_status, then project_check, and explain what this Protoboard project is and what the check found.

Other MCP clients

protoboard agents setup also knows Claude Desktop, Gemini CLI and Cline. For any other client that runs local (stdio) servers, protoboard agents config prints the entry. It is a server named protoboard-stack whose command is the launcher above, with no arguments, environment variables or key; restart the client after adding it. In the common mcpServers form:

{
  "mcpServers": {
    "protoboard-stack": {
      "command": "/Users/you/.config/protoboard/agents/protoboard-mcp",
      "args": []
    }
  }
}

In these examples, put your own home folder in place of /Users/you. On Windows the command is cmd with the arguments /c and the launcher's full path; protoboard agents config prints it.

Then run protoboard agents refresh once, so the launcher is there.

Your first project

In the editor

Open the Protoboard side bar. In a window with no folder, or an empty folder, it offers New Project; in a folder that holds a Protoboard project not set up on this machine yet (one you cloned or were sent), it offers Initialize. Both are in the command palette too (Protoboard: New Project…, Protoboard: Initialize Project). Neither needs npm.

New Project asks what to start from and where:

Starting pointWhat it is
EmptyNothing yet: you and your agent start from a blank project.
iotA battery-powered Wi-Fi and Bluetooth device: an ESP32-C3 board on a lithium cell, with its PCB, firmware configuration and an enclosure folder.
wearableA Bluetooth wearable: an nRF52840 board on a lithium cell, with its PCB, Zephyr board files and a case folder.
droneA multirotor flight stack: flight controller, ESC, battery and receiver, to grow into a drone.

When it is made, choose Open in New Window. The editor then asks "Do you trust the authors of the files in this folder?": choose Yes, I trust the authors. The Protoboard views stay off until you do.

Protoboard then asks once more, for this project: Run the code of "…"? Checking and showing a project runs its code, so choose Trust and Run for a project you made or got from someone you trust. Don't Run keeps it off; Protoboard: Trust This Project's Code… asks again later.

The viewer opens on the system as a diagram. Double-click a module to open it; the 3D tab shows the assembled model. Click a module to see it in the Protoboard Inspector on the right. The DRC panel at the bottom shows what the checks find, and the project is checked again each time you save.

From the command line

protoboard init --list
protoboard init my-project --template iot
code my-project

Without --template, init makes an empty project. The project uses the Protoboard installed for your user: there is no npm install to run in it. A template's parts come from the Protoboard library: signed out, init makes the project and says how to fetch them later (--no-parts leaves them out on purpose). In the project:

protoboard check
protoboard build
protoboard dev --open

check runs every design rule check (exit code 1 when it finds an error), build writes the derived data to .protoboard/build/, and dev --open serves the viewer in your browser and redraws it as files change. In the editor, Protoboard: Open Viewer and Protoboard: Check do the same.

If you are an agent doing this for someone: use plain protoboard init, in the folder and with the starting point they chose. Never tell them to run npm in a project: projects use the Protoboard installed on the machine. Look at the project (protoboard inspect, protoboard check) before you describe it.

Signing in for the library

Your projects, the viewer, checks, builds and releases work without an account. Signing in is for the Protoboard library, all of it: searching and browsing its parts (parts search, parts taxonomy, libraries), adding them to a project (parts add, a template's parts at init), update checks (parts update, parts list --check), offers and prices (parts offers, parts prices), and publishing a part (parts publish). Signed out, those stop before changing anything, with one line saying to sign in, and exit code 4.

In the editor: Sign in in the status bar, or Protoboard: Sign In from the command palette. A browser page opens; the editor continues by itself when you are signed in. In a remote window (SSH, WSL, a container), or when no browser opens, use Protoboard: Sign In with a Code (Remote or Headless) and approve the code on any device.

In a terminal:

protoboard login
protoboard whoami --check

protoboard login --device prints a code to approve on another device, for a machine with no browser. protoboard logout signs out. The sign-in is kept in your system's keychain, else in a file only you can read, and never in a project. In CI, set PROTOBOARD_CLOUD_TOKEN to a service token instead.

To manage the account (its profile, where it is signed in, sign out everywhere, delete it): protoboard account prints its page and opens it, and Manage Account in Protoboard Settings or the Cloud view opens it from the editor.

If you are an agent doing this for someone: you cannot sign in for them and must not work around it. Ask whether they want the library now; if they do, ask them to sign in and to tell you when the status bar shows their account. Everything else goes on without it.

Updating

A project from the first beta releases

A project made with the beta releases, before Protoboard was public, is brought up to date with one command in the project:

protoboard upgrade

In the editor, opening such a project offers Update Project to Protoboard with the version the extension carries (Initialize offers it too): it does the same.

It says what it changed. Commit or copy the project first, so you can see the changes.

Uninstalling

Nothing below touches your projects.

  1. Disconnect your agents: protoboard agents remove (it asks about each), or Disconnect on each row of Protoboard: Open Settings.
  2. Sign out: protoboard logout.
  3. Uninstall the extension from the Extensions view, or with code --uninstall-extension deltarobotics.vscode-protoboard (cursor, windsurf for those editors).
  4. If you installed the command line with npm: npm uninstall -g @protoboardai/cli.
  5. Take the command off your PATH: delete the line marked protoboard-path from your shell's start file (macOS, Linux), or remove %USERPROFILE%\.protoboard\bin from your user Path (Windows: Settings, System, About, Advanced system settings, Environment Variables).
  6. Delete Protoboard's folders: ~/.protoboard (the stack copies and the command) and ~/.config/protoboard (the agents' launcher, and the sign-in when it is kept in a file); on Windows %USERPROFILE%\.protoboard and %APPDATA%\protoboard.

Troubleshooting

Start with the two commands that say how this machine is set up:

protoboard doctor
protoboard agents

doctor prints, in order: the version and the Build (a release, or a development build with its commit); the Account for the library; Packages (which CLI runs, which Node.js, the stack copies in ~/.protoboard/stack and the extensions that carry them); and, in a project, its Extensions, the Tools they need (each with ✓ or ✗ and how to install what is missing), the Runtimes in .protoboard/tools, the Skills, and whether AGENTS.md and CLAUDE.md are current. protoboard doctor --format json gives the same as data. protoboard agents lists each agent found and whether it is connected.

Where the logs are. In the editor, Protoboard: Show Log opens the Protoboard output channel: which CLI and Node.js run and why, each check, the dev server and every library call. The command line prints to the terminal; add --format json for the details. An agent's MCP server logs to the agent: in Claude Code, /mcp shows whether protoboard-stack started.

Exit codes. 0 is success, 1 is findings (a check with errors), 2 a command that failed, 4 a library command that needs a sign-in.

You seeDo this
protoboard: command not found (in PowerShell: "protoboard is not recognized")Open a new terminal: one opened before the install does not have it. Inside the editor the setting protoboard.terminal.addCommand must be on. For other terminals, run Protoboard: Add the protoboard Command to PATH, then open a new terminal; meanwhile the full path works (~/.protoboard/bin/protoboard, %USERPROFILE%\.protoboard\bin\protoboard.cmd).
code: command not foundSee the code command in your system's install section above.
The editor refuses to install the extension because it is too oldUpdate the editor. The extension needs one built on VS Code 1.106 or later.
"The Protoboard extension carries its stack for … not for …"Your system is not one the extension carries Protoboard for (Alpine Linux, for example): install the command line with npm.
The Protoboard views are empty or missingThe folder is not trusted yet: run Workspaces: Manage Workspace Trust and press Trust. Protoboard: Show Log says what the extension did.
"Protoboard does not run …'s code, so it is not checked or shown"You chose Don't Run when Protoboard asked about the project: run Protoboard: Trust This Project's Code… and choose Trust and Run.
The project "needs its packages", or the views say it is not set upPress Initialize in the Protoboard side bar. Do not run npm install in the project unless it was made with --stack project.
The agent does not list Protoboard's toolsprotoboard agents shows whether it is connected; connect it, then start a new session or restart the agent (some agents also ask you to turn a new server on). In a client set up by hand, run protoboard agents refresh so the launcher exists.
protoboard-mcp: Node.js 22 or later was not foundThe launcher found no Node.js and no editor runtime. Open the editor with the extension once (it records its runtime), or install Node.js 22 or later, then run protoboard agents setup again.
… needs a Protoboard account: sign in with protoboard login (exit code 4), or the Library shows a sign-in cardOnly the library needs an account. Sign in: Protoboard: Sign In, or protoboard login.
You signed in, and the editor still says "Sign in"Run Protoboard: Check the Account Again. Still the same: protoboard whoami --check says what the service answers; then Developer: Reload Window.
"The Protoboard library could not be reached"You are offline, or the service is slow to wake: connect, then Check Again. Your project works offline.
The wrong accountProtoboard: Sign Out, then Protoboard: Sign In; or protoboard logout, then protoboard login.
A CAD step is refused or skippedThe 3D generators need the CAD runtime, once per project: Protoboard: Install a Tool Runtime (CAD, Circuit)…, or protoboard tools install cad. Boards need protoboard tools install circuit, which needs Node.js with npm.
tools install cad says "no Python that can create this runtime was found"It tried every Python on the machine and lists them. It prints what to run (on macOS brew install uv && uv python install 3.12); --python <path> names one, --clean removes what a failed attempt left. On Windows, install Python from python.org and open a new terminal.
Documents fail with required tools unavailable: chromeInstall Google Chrome, Chromium, Microsoft Edge or Brave, or set CHROME to its executable, then open a new terminal and restart the editor. If it also names poppler: brew install poppler (macOS) or sudo apt install poppler-utils (Debian, Ubuntu).
Something in Protoboard looks wrongOpen an issue on the repository with the command, what it printed, and the output of protoboard doctor.

If you are an agent doing this for someone: when something fails, run protoboard doctor and protoboard agents, read what they say, and tell the person in plain words what is missing and what fixing it changes, before you fix it.