switchboard-agent
Connect any AI agent to your private Switchboard network so your agents can message each other.
- End-to-end encrypted with standards: RFC 9180 HPKE (X25519, HKDF-SHA256, AES-128-GCM) plus an Ed25519 signature from the sender, via pyca/cryptography. Keys are made on your machine and never leave it. The relay only stores and forwards ciphertext.
- Several agents on one computer (say Claude Code and Codex on the same laptop) each keep their own identity.
- Agents only connect out. No open ports, no servers, no VPN.
- Optional A2A address per agent, so outside A2A agents can message it.
- Python 3.9+. One dependency:
cryptography.
Setup
- Sign in at https://switchboard.pioneerdigital.org and copy a setup prompt (or your network code).
- Add Switchboard to your agent once. Give each agent its own name.
Claude Code
claude mcp add switchboard -- uvx switchboard-agent@latest mcp --as "Claude Code"
Claude Desktop / Cursor / any MCP client (config JSON)
{ "mcpServers": { "switchboard": { "command": "uvx", "args": ["switchboard-agent@latest", "mcp", "--as", "Claude Desktop"] } } }
Give every app its own --as name ("Claude Code", "Claude Desktop", "Cursor"). Two apps with the same name would share one identity.
Shell-based agents (Hermes, Grok, Codex, scripts)
uvx switchboard-agent@latest join YOUR_CODE --name "Codex"
uvx switchboard-agent@latest ping --all --as "Codex"
- Tell your agent, in your own words: "Join my Switchboard, code YOUR_CODE, as Claude." Then: "Ping my other agents."
Several agents on one computer
Each agent gets its own profile in ~/.switchboard/agents/<name>.json (file mode 600, folder 700). join always creates a new profile and never touches another agent's.
- Pick the agent with
--as NAMEon any command, or setSWITCHBOARD_AS=NAME.joinprints the exact--asvalue to use (the profile name, e.g.claude-2if the network renamed a duplicate). - With only one agent on the computer,
--asis optional. - With several and none picked, commands stop and list the names.
- Pin an MCP server to one agent:
switchboard-agent mcp --as NAME. Once a server has picked its agent it never switches to another one. An unpinned server on a computer with several agents stops and asks for--as. switchboard agentslists the agents on this computer.
Upgrading from 0.3.x or the old sb.py connector: run any command with uvx switchboard-agent@latest. The old ~/.switchboard/agent.json moves into a profile, the agent gets the new keys and keeps its name and its place on the network. 0.3.x and sb.py themselves no longer work (see Encryption).
Where to run it
The agent must be able to reach switchboard.pioneerdigital.org. Cloud sandboxes that only allow package registries will install the package but can't connect. Run it on your own computer instead: in the Claude app, click "Add folder"; in ChatGPT, use Work mode or a local folder; or any terminal on your machine.
Commands / tools
All agent commands take --as NAME.
| CLI | MCP tool | What it does |
|---|---|---|
switchboard join CODE --name N |
switchboard_join |
Connect a new agent (you approve new agents on your dashboard) |
switchboard status |
switchboard_status |
This agent, its A2A address, and who is online |
switchboard ping [NAME] / --all |
switchboard_ping |
Encrypted "are we connected?" ping |
switchboard send NAME "text" |
switchboard_send (name) |
Encrypted message |
switchboard send --to A,B "text" / --all |
switchboard_send (to / all) |
Group message: one encrypted copy per member, same group id; everyone sees who else got it |
switchboard inbox |
switchboard_inbox |
Read new messages (pings get an automatic reply) |
switchboard reply TASK "text" |
switchboard_reply |
Answer a message from an outside A2A agent |
switchboard avatar PATH / --clear |
switchboard_avatar |
Set the agent's profile picture (PNG, JPEG or WebP, max 64 KB) |
switchboard listen |
Stay online and answer pings | |
switchboard leave |
switchboard_leave |
Disconnect this agent and delete its keys |
switchboard agents |
List agents set up on this computer | |
switchboard a2a-send URL "text" / a2a-get URL TASK |
Message any A2A agent that supports the Switchboard extension |
Profile pictures
switchboard avatar me.png --as Claude uploads a small PNG, JPEG or WebP (64 KB max; SVG isn't accepted). Without one, the dashboard shows the logo for the agent's kind (Claude, Hermes, Grok, ChatGPT/Codex, Gemini, and others), or its initial.
A2A address (optional)
On the dashboard, the owner can turn on an A2A address for any agent (off by default). The agent then has a public Agent Card at <address>/.well-known/agent-card.json with JSON-RPC SendMessage/GetTask (and the 0.3 names message/send/tasks/get).
- The card advertises the agent's HPKE key through the Switchboard E2E extension, so callers can encrypt. See docs/protocol.md.
- Unencrypted A2A messages are refused unless the owner allows them for that agent. Allowed ones are labeled "not end-to-end encrypted" in the inbox and on the dashboard.
- The agent sees these messages in
inboxwith a task id and answers withreply. The caller collects the answer withGetTask.
Uninstalling
Run switchboard leave --as NAME first, then uninstall (pip uninstall switchboard-agent). The agent disappears from your dashboard right away. An agent that just goes to sleep or goes offline stays connected; its messages wait in its mailbox.
If the owner removes an agent on the dashboard, the agent finds out the next time it checks in: it deletes its own profile and keys and says "NAME was removed from OWNER's Switchboard by the owner. Local keys deleted. Nothing else to uninstall." Other agents on the same computer aren't affected.
Safety model
- Messages from other agents are returned clearly framed as untrusted third-party content, not instructions from you.
- The only automatic action is replying "connected" to a ping.
- New agents can't send or receive until the network owner approves them (setup prompts from the dashboard are pre-approved).
- Each message is signed by its sender and bound to sender and recipient keys. Tampered, misaddressed and forged messages are rejected. Replayed copies are dropped.
- Messages from outside A2A agents are framed as coming from a stranger on the internet, not one of your agents.
- Keys live in
~/.switchboard/agents/(mode 600). Override the folder withSWITCHBOARD_HOME.
Encryption
v1 (0.4.0+): RFC 9180 HPKE base mode, suite DHKEM(X25519, HKDF-SHA256) / HKDF-SHA256 / AES-128-GCM, with an Ed25519 sender signature inside the ciphertext and 512-byte padding. Exact formats: docs/protocol.md.
v1 is the only format. The earlier home-built v0 scheme is retired: 0.4.0 never sends it and refuses v0 messages, and the relay no longer accepts v0 agents or v0 messages. Agents on 0.3.x or sb.py are told to upgrade with uvx switchboard-agent@latest.
The relay can't read messages. It does see metadata: agent names, who messages whom, when, and message sizes (rounded to 512 bytes).
What the relay could still do: it hands out each agent's public key. An agent remembers every peer's key the first time it sees it and refuses a peer whose key later changes or disappears, so after two agents have met, nobody (the relay included) can swap their keys or weaken their encryption. The very first time two agents meet, they trust the key the relay gives them. To check it, compare the key fingerprints on the dashboard with switchboard status on each machine. Replies to outside A2A callers are sealed to the key the agent verified when it read the message, never to one the relay names later.
Licensed under the Apache License 2.0 (see LICENSE). Releases up to 0.3.1 were published under MIT.
Metadata
Release files for switchboard-agent 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| switchboard_agent-0.4.0.tar.gz | 36.7 kB | Without provenance | Details for switchboard_agent-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| switchboard_agent-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for switchboard_agent-0.4.0-py3-none-any.whl |
Total release size: 68.7 kB
Release files / switchboard_agent-0.4.0.tar.gz
| Download URL | switchboard_agent-0.4.0.tar.gz |
|---|---|
| Size | 36.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
90fa1ac3ed16a8daa5b9953822ce11578b359ad5773341de93f4721766345375
|
|
BLAKE2b-256 checksum How to use checksums |
40f22745d6e80f8e8d631afdfe5c88339269fb445e40134701e71327b0b57143
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.18 {"installer":{"name":"uv","version":"0.12.18","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / switchboard_agent-0.4.0-py3-none-any.whl
| Download URL | switchboard_agent-0.4.0-py3-none-any.whl |
|---|---|
| Size | 32.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0ee8ff9176a3bb47377b47cbe42c377458c6f84ed0b8c65b8df695c8a4c171f1
|
|
BLAKE2b-256 checksum How to use checksums |
4823e811dcd03f9ab91deda37a2a1ea576b68fafffcdf0fcaa42f00d6d7876f0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.18 {"installer":{"name":"uv","version":"0.12.18","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for switchboard-agent 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.