Metadata-Version: 2.5
Name: switchboard-connector
Version: 0.2.5
Summary: Switchboard: the local client (connector, harness adapters, mailbox) for the verifiable A2A directory
License-File: LICENSE.md
Requires-Python: >=3.12
Requires-Dist: a2a-sdk[fastapi,postgresql]==1.1.2
Requires-Dist: cryptography<51,>=45
Requires-Dist: httpx<1,>=0.27
Requires-Dist: mcp==1.29.0
Requires-Dist: platformdirs<5,>=4
Requires-Dist: provably-sdk<1,>=0.3.2
Requires-Dist: psycopg[binary]<4,>=3.1
Requires-Dist: pydantic<3,>=2
Requires-Dist: python-dotenv>=1.2.3
Requires-Dist: sourcerykit<2,>=1.4.1
Requires-Dist: structlog>=26.1.0
Requires-Dist: uvicorn<1,>=0.35
Requires-Dist: websockets<17,>=15
Description-Content-Type: text/markdown

# Switchboard

<div align="center">
  <a href="https://github.com/ProvablyAI/switchboard/actions/workflows/ci.yml">
    <img src="https://github.com/ProvablyAI/switchboard/actions/workflows/ci.yml/badge.svg" alt="CI" />
  </a>
  <a href="LICENSE.md">
    <img src="https://img.shields.io/badge/license-BSL%201.1-blue" alt="License: BSL 1.1" />
  </a>
</div>

Switchboard lets people share selected local agent sessions (Codex, Claude Code,
Hermes, OpenCode, OpenClaw) with permitted people in their workspace. Prompts,
answers and transcripts never leave the machine that ran them: the hosted
backend only routes opaque ciphertext between paired devices.

This repo is the local side: the connector (Python CLI, resident service and
MCP server) and the desktop app. The hosted backend and web app live in
[switchboard-control](https://github.com/ProvablyAI/switchboard-control).

## How it works

```mermaid
flowchart LR
    U[Caller asks a question] --> H[Caller harness]
    H <-->|MCP over stdio| L[Local MCP server]
    L <-->|loopback| C[Caller connector]
    C -->|signed encrypted envelope| M[Switchboard backend<br/>directory, grants, opaque mailbox]
    M -->|ciphertext only| W[Owner connector<br/>mailbox worker]
    W -->|decrypt, recheck grant and policy| A[Harness adapter]
    A --> S[Owner session<br/>or caller-isolated fork]
    A -->|encrypted answer, reverse path| H
```

- The **connector** discovers local harness sessions, publishes the shared ones
  to the backend directory, and runs the mailbox worker that executes incoming
  requests after rechecking the grant and the owner's local policy.
- The **MCP server** (launched by each harness) and the bundled
  `switchboard-ask` skill let an agent resolve and call another agent:
  `ask.research` is your own local agent, `ask.sim.research` an agent shared
  with you.
- The **desktop app** drives the CLI and the backend API; it has no business
  logic of its own. See [apps/desktop](apps/desktop/README.md).

```text
src/switchboard/
├── harness/          adapters for Codex, Hermes, Claude Code, OpenCode and OpenClaw
├── local/            the resident service: CLI, connector, approval bridge, policy
│   ├── owner_app/    owner-local A2A app (task API, agent cards, web UI)
│   ├── mcp/          harness-facing MCP server and remote calls
│   ├── policy/       owner policy authoring and enforcement
│   └── skills/       the switchboard-ask skill installed into every harness
├── mailbox/          envelope crypto, client and worker, QEDB ledger
└── qedb/             A2A task store and proofs
apps/desktop/         Tauri desktop app
docs/                 harness registration details
tests/                mirrors src/switchboard
```

## Getting started

Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/).

```bash
uv sync
make check        # pre-commit hooks, tests and build: the CI gate
```

`make lint`, `make format`, `make typecheck` and `make test` run the pieces
individually.

To run the connector from your checkout against a backend:

```bash
uv run switchboard install --switchboard-url <control backend URL>
uv run switchboard pair --device-name "dev machine"
uv run switchboard status
```

`install` registers your harnesses and a per-user service (LaunchAgent,
systemd user unit or Scheduled Task); `start`, `stop` and `uninstall` manage it.
End users install the published package instead: `uv tool install
switchboard-connector`.

The connector (`connector-v*` tag, PyPI) and the desktop app (`desktop-v*` tag,
[switchboard-releases](https://github.com/ProvablyAI/switchboard-releases)) are
released separately by CI.

## License

Business Source License 1.1, see [LICENSE.md](LICENSE.md).
