CCSwitchboard
Self-hosted · you run all of it

Set up your own CCSwitchboard.

CCSwitchboard lets your chat threads dispatch real jobs to machines you own and streams the results back inline. There's one thing to stand up first — your relay — and everything else just joins it.

Start — stand up a relay → What is this?

The whole model in one line

A relay is the hub — it holds the jobs, hands out tokens, and dispatches work. Agents, the browser extension, and anything else are just clients of it. Each client needs exactly two things: your relay's URL and a token.

CCSwitchboard architecture: one self-hosted relay is the hub, with agents, a browser extension, and a popup connecting to it as clients.

Your relay is the hub; each client (agent, extension, popup) just needs its URL and a token.

1

Set up your relay

The relay is a small PHP + SQLite app with no build step and no database server. Pick where it lives — each option lists its own requirements, and you can move it later.

Relay on shared hosting

Works on a no-shell cPanel box. Upload, unzip, open it — the relay sets itself up on first visit.

Personalize

A subdomain like relay.yourdomain.com is fine — just type it in full. Fills in every command and URL below, including what Copy puts on your clipboard. Stored in this browser only.

Before you start

PHP 8.0+pdo_sqliteopensslA way to upload + unzip

HTTPS on the domain is required, not just recommended: the dashboard's login cookie is set Secure, so over plain HTTP you will not stay logged in. cPanel's AutoSSL is fine — turn it on before you start.

  1. Download the relay bundle.
    Download ccsw-relay-php.zip

    About 190 KB. Contains board/ (the relay itself) and data/ (its private store, pre-locked against web access).

  2. Upload it to your site and unzip it in public_html. cPanel's File Manager does both. You should end up with:
    public_html/ccswitchboard/board/ <- the relay public_html/ccswitchboard/data/ <- database + token (not web-readable)

    Keep that layout. The login cookie is scoped to /ccswitchboard/board, and the data/ folder ships an .htaccess that keeps your database and token off the web. Serving it at another depth breaks login.

  3. Open it — that's the whole setup.
    https://yourdomain.com/ccswitchboard/board/

    The first visit creates the database, generates your admin token, claims the relay and signs you in. You'll see the token once, on screen — save it somewhere safe. Nothing to run, no files to go and read.

    Open it yourself, promptly. A relay belongs to the first browser that reaches it, so don't leave a freshly uploaded one sitting unopened. If that screen ever appears when you weren't expecting it, someone else got there first — delete it and re-upload.

The address without ?token= is your relay URL — that's what the extension and your machines connect to. Your token signs you in from any other browser.

Relay on a VPS

Same bundle as the shared-hosting path, served by your own web server with automatic HTTPS.

Personalize

A subdomain like relay.yourdomain.com is fine — just type it in full. Fills in every command and URL below, including what Copy puts on your clipboard. Stored in this browser only.

Before you start

Linux + rootPHP 8.0+ / php-fpmpdo_sqlitePorts 80 + 443A domain pointed at the box

Caddy is used below because it provisions and renews TLS certificates on its own. nginx + certbot works just as well if that's what you already run.

  1. Fetch and unpack the relay into your web root:
    curl -fsSL https://github.com/DabbleLabs-UK/ccswitchboard/releases/latest/download/ccsw-relay-php.zip -o ccsw.zip \ && sudo unzip -oq ccsw.zip -d /var/www

    Gives you /var/www/ccswitchboard/board/ and /var/www/ccswitchboard/data/.

  2. Serve it. A minimal Caddyfile:
    yourdomain.com { root * /var/www php_fastcgi unix//run/php/php-fpm.sock file_server # data/ holds the SQLite database and your auth token. The bundle's # .htaccess only applies to Apache/LiteSpeed, so block it here too. @data path /ccswitchboard/data/* respond @data 403 }

    The board must stay at /ccswitchboard/board/ — the login cookie is scoped to that path.

  3. Open it — that's the whole setup.
    https://yourdomain.com/ccswitchboard/board/

    First visit creates the database, generates your admin token, claims the relay and signs you in. The token is shown once on screen — save it. Nothing to grep out of a config file.

    Do this yourself, promptly. The relay belongs to the first browser that reaches it. If that screen appears unexpectedly, someone beat you to it — wipe it and redeploy.

  4. Optional, recommended: move the data outside the web root entirely by setting CCSW_DB_PATH (e.g. /home/you/private/ccsw/jobs.sqlite) in your php-fpm pool. The relay creates the file and its directory on first request.

A one-command VPS installer is planned; today it's these three steps.

Relay on this machine

Great for testing — relay, agent, and browser can all live on one box.

Personalize

Only used on the macOS and Linux steps below; the Windows relay picks its own port. Stored in this browser only.

Before you start

Windows 10/11 x64Nothing else to install

The relay ships as a single self-contained .exe with PHP bundled inside. You do not need PHP on the machine.

  1. Download the relay.
    Download ccsw-relay-windows-x64.exe
  2. Run it. It starts in the system tray and picks a free port automatically.
  3. Open the dashboard from the tray icon — right-click the CCSwitchboard icon and choose Open dashboard. It logs you in automatically, no token to copy.

    The same menu has Copy relay token for when you set up the browser extension, and shows your relay URL at the top.

Before you start

PHP 8.0+ with pdo_sqlitecurl + unzip (built in)

macOS no longer ships PHP. If php -v says nothing, install it first:

brew install php
  1. Download, unpack and start the relay — one command, run it in an empty folder:
    curl -fsSL https://github.com/DabbleLabs-UK/ccswitchboard/releases/latest/download/ccsw-relay-php.zip -o ccsw.zip \ && unzip -oq ccsw.zip \ && php -S localhost:8787

    Leave that running — it is the relay.

  2. Open the dashboard — it signs you in:
    http://localhost:8787/ccswitchboard/board/

    First visit creates the database, generates your token, claims the relay and logs you in. The token is shown once — save it; you'll want it for the browser extension.

A native macOS build (like the Windows one, no PHP needed) is planned.

Before you start

PHP 8.0+ CLI with pdo_sqlitecurl + unzip

If php -v says nothing, or the relay complains about SQLite, install both pieces (Debian/Ubuntu):

sudo apt install php-cli php-sqlite3 unzip
  1. Download, unpack and start the relay — one command, run it in an empty folder:
    curl -fsSL https://github.com/DabbleLabs-UK/ccswitchboard/releases/latest/download/ccsw-relay-php.zip -o ccsw.zip \ && unzip -oq ccsw.zip \ && php -S localhost:8787

    Leave that running — it is the relay.

  2. Open the dashboard — it signs you in:
    http://localhost:8787/ccswitchboard/board/

    First visit creates the database, generates your token, claims the relay and logs you in. The token is shown once — save it; you'll want it for the browser extension.

A native Linux build (like the Windows one, no PHP needed) is planned.

Heads up: a localhost relay is only reachable from this machine. To join agents on other machines later, move the relay to a VPS or shared host — it's the same bundle, and you can copy the data/ folder across to keep your history.

2

Add your machines

A machine is a computer that actually runs the work. Your relay hands them out jobs — you add them from the relay itself, not from here.

One machine, one agent. The agent is a small background program that sits on that computer, asks your relay for work, runs it, and streams the output back. The relay never runs anything itself — it coordinates, the machines do the work.

Which computer should I use?

  • Your main PC — simplest. It already has your files and logins. Jobs only run while it's on.
  • A VM — isolated and disposable. Nothing a job does can touch your real desktop, and you can reset it to clean in seconds.
  • A spare always-on box — most reliable. Jobs you dispatch from your phone at 2am actually run, because nothing is asleep.

You don't have to prepare any of them. The installer sets up the toolchain it needs — .NET, Git, Node, Claude Code — on the machine you run it on.

What adding one looks like

So you recognise it when you get there, the whole flow is five clicks on your own relay:

  1. Open your Board — the relay you just stood up.
  2. Go to Machines.
  3. Click Add a machine and give it a name (desktop, vm-1 — just how you'll recognise it in a job list).
  4. Download that machine's installer, and run it on that machine.
  5. Watch it come online on the Machines page. That's it — it's in your pool.

Why it isn't on this page: the installer and token are generated by your relay, per machine — each machine gets its own credential so you can revoke one without disturbing the others. There is no generic download here to give you; yours only exists once your relay mints it.

3

Install the browser extension (optional)

This is what lets a chat thread dispatch jobs to your relay — and get each result typed back into the thread as it completes. It's not necessary if you plan to use the client built into the relay instead of claude.ai

  1. Download the extension.
    Download ccsw-browser-extension.zip
  2. Unzip it into its own empty folder, somewhere permanent. The zip has no wrapper folder inside it, so unzipping it into an existing folder will scatter its files — and your browser loads the extension from that folder every time, so don't leave it in Downloads.
  3. Load it. In Chrome or Edge, open chrome://extensions, turn on Developer mode, click Load unpacked, and pick that folder.

    Manifest V3, so Chrome and Edge both work. Firefox is not supported yet.

  4. Point it at your relay — open the extension and give it your relay URL and a token. That's the same pair every client needs.