Bridge v0.1.1

Install the Bridge

The SwarmDeck Bridge is a small daemon that runs on your machine and connects your local AI agents to your SwarmDeck dashboard over a secure WebSocket. No port forwarding. No VPN. Three commands, about five minutes.

Already have Node.js 22+ and a SwarmDeck account? Skip to Step 1. Otherwise, check the prerequisites below first.

Before you begin

Node.js 22 or newer
Download the LTS installer from nodejs.org and accept the defaults. Already installed? Verify in a terminal:
```
node --version
```
If the number is below v22.0.0, upgrade before continuing. If you see "not recognized," close the terminal and open a fresh one after installing.
A SwarmDeck account
Sign up or log in. Pairing (Step 2) requires being signed in on a separate browser window or phone.
Supported platforms
Windows 10/11 (PowerShell), macOS (Terminal or any shell), Linux (any modern distribution). Commands are the same across platforms; OS-specific notes are called out where they matter.
Outbound internet access
The bridge opens an outbound WebSocket to Supabase Realtime (HTTPS port 443). No inbound ports are opened on your machine. Corporate firewalls that block WebSocket upgrades or Supabase domains will prevent pairing.

Install the bridge

Open a terminal and run this single command. npm downloads the tarball straight from swarmdeck.studio and installs the swarmdeck-bridge command globally.

npm install -g https://swarmdeck.studio/install/swarmdeck-bridge-0.1.1.tgz

Confirm it installed:

swarmdeck-bridge --version

Expected output: 0.1.1. If the command is not recognized, close and reopen your terminal so PATH picks up the new binary.

Windows notes

Use PowerShell (not Command Prompt). Open it from the Start menu or press Win+R, type powershell, Enter.

Global npm installs on Windows usually don't need admin rights. If you do see a permission error, open PowerShell "as administrator" and retry.

macOS / Linux notes

If npm install -g fails with EACCES or "permission denied", npm's default global prefix (typically /usr/local) is not writable by your user. Two safe options:

Prefix with sudo — quick, but runs the install as root.

Move npm's prefix to your home directory so -g no longer needs root:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc  # or ~/.bashrc
# then open a new terminal

After that, retry the install command without sudo.

Install from a downloaded file (offline / USB transfer)

Download the tarball and install from disk — useful for air-gapped machines or transferring to a computer without direct internet access to this site.

Download swarmdeck-bridge-0.1.1.tgz and move it to the target machine (USB, email, cloud share — whatever works).
Windows: Right-click the downloaded file and choose "Copy as path" — this gives you the real file path even when OneDrive has redirected your Desktop. Paste it after npm install -g:
Windows PowerShell
```
npm install -g "C:\Users\<you>\Desktop\swarmdeck-bridge-0.1.1.tgz"
```

macOS / Linux:

macOS / Linux shell

npm install -g ~/Downloads/swarmdeck-bridge-0.1.1.tgz

Verify with swarmdeck-bridge --version (expect 0.1.1). Reopen your terminal first if the command is not recognized.

Pair with your account

Pairing links this machine to your SwarmDeck account so the dashboard can send and receive commands. Each code is valid for 5 minutes, so keep the terminal handy.

a
In any signed-in browser (your laptop, phone, whatever), open /dashboard/pair and click Generate pair code. You'll see a 6-character code such as ABC123.
b
Back in the terminal on the machine you just installed to, type your code into the highlighted field below, then click Copy:
swarmdeck-bridge pair --api-url=https://swarmdeck.studio
The copied line already has your code substituted -- paste it straight into the terminal and press Enter.
c
You should see a line ending in Paired successfully! Run 'swarmdeck-bridge start' to connect. Your credentials are saved to ~/.swarmdeck/config.json with user-only permissions (mode 0600).

Start the bridge

Run the daemon in the foreground. Leave the terminal open — the bridge stays connected until you stop it.

swarmdeck-bridge start

What success looks like

[bridge] Starting SwarmDeck Bridge v0.1.1
[bridge] User: 00000000-0000-0000-0000-000000000000
[bridge] Supabase: https://<project>.supabase.co
[bridge] All systems online. Press Ctrl+C to stop.
[bridge] Command listener: active

Open your dashboard in a browser — a green bridge-online indicator should appear within a few seconds. Trigger any safe command (for example, Git Status) and the bridge logs it in the terminal.

Run it unattended / at startup

For a machine you want the bridge running on all the time, use any process supervisor of your choice so it starts on boot and restarts on crash. Native examples for each platform are shown below.

macOS (launchd):

# ~/Library/LaunchAgents/com.swarmdeck.bridge.plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.swarmdeck.bridge</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/swarmdeck-bridge</string>
    <string>start</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
</dict>
</plist>

Then: launchctl load ~/Library/LaunchAgents/com.swarmdeck.bridge.plist

Linux (systemd user service):

# ~/.config/systemd/user/swarmdeck-bridge.service
[Unit]
Description=SwarmDeck Bridge
After=network-online.target

[Service]
ExecStart=%h/.npm-global/bin/swarmdeck-bridge start
Restart=on-failure

[Install]
WantedBy=default.target

Then: systemctl --user enable --now swarmdeck-bridge

Windows:

Use NSSM to wrap swarmdeck-bridge start as a Windows service, or create a Task Scheduler entry that runs the same command at logon.

Troubleshooting

TAR_BAD_ARCHIVE: Unrecognized archive format: npm downloaded something that is not a tarball — almost always an HTML page from a redirect. Make sure you are copying the command from this page as shown (it points at swarmdeck.studio) rather than typing it from memory. To confirm the file is reachable before installing:
curl -I https://swarmdeck.studio/install/swarmdeck-bridge-0.1.1.tgz
A working tarball returns HTTP/1.1 200 OK. A redirect (307) means you are hitting a host that does not host this version.
EACCES / permission denied (macOS / Linux): npm's default global prefix needs root. Either prefix the install with sudo, or move the prefix to your home directory — see macOS / Linux notes under Step 1.
swarmdeck-bridge: command not found: Close the terminal and open a fresh one — the installer added the command to PATH, but existing shells have the old PATH cached.
Pair command times out or says "expired": Pairing codes are valid for 5 minutes. Generate a fresh one at /dashboard/pair and run the pair command immediately.
FATAL: SUPABASE_SERVICE_ROLE_KEY is present: The bridge refuses to start with a Supabase service-role key in the environment — a safety guard to prevent accidental privilege exposure. Unset SUPABASE_SERVICE_ROLE_KEY in the current shell and retry.
Could not connect to SwarmDeck: The machine cannot reach swarmdeck.studio or the Supabase Realtime endpoint. Check your internet connection, any VPN or proxy, and whether a corporate firewall blocks WebSocket (wss://) traffic.
Auth session expired / refresh token invalid: Your pairing credentials were revoked or expired. Run Step 2 again to pair with a fresh code — the previous ~/.swarmdeck/config.json is safely overwritten.
Something else?: Copy the full terminal output and email it to support@swarmdeck.studio — include your OS and Node.js version (node --version).

Uninstall

Stops the daemon (if running), removes the global command, and deletes your saved credentials.

Windows PowerShell

# In the window where the bridge is running, press Ctrl+C first.
npm uninstall -g @swarmdeck/bridge
Remove-Item -Recurse -Force $env:USERPROFILE\.swarmdeck

macOS / Linux

# In the shell where the bridge is running, press Ctrl+C first.
npm uninstall -g @swarmdeck/bridge
rm -rf ~/.swarmdeck

To also stop the machine from showing on the dashboard, open /dashboard/pair and click Revoke next to this bridge.