Run Raven on a remote host

What you need

Use Raven 0.9.5 or later on your Mac, a Raven account, and a Linux host you can reach over SSH for setup. The server runs raven-muxd, which owns the shells and agents; the Mac runs the window. The server needs no display or GPU.

Both machines need outbound network access to Raven’s service on TCP port 443. You do not need to open the server’s remote-listener ports, forward a router port, or install a VPN. These examples use Debian or Ubuntu and the SSH alias build-host; replace it with your own SSH destination.

The hosted relay is part of Raven’s account service. Signing the server in registers its device with the relay. Pairing below grants your desktop access to that server’s whole terminal session; membership in the same team alone does not grant that access.

1. Install the daemon on the server

On a Linux x86-64 host, install the standalone daemon and CLI. No desktop or Rust toolchain is needed. Check the download page for the package’s glibc requirement; OpenSSL 3 and libstdc++ are also required. Run the installer as your normal user, not with sudo.

curl -fsSL https://raven.thousandbirds.ai/install-mux.sh -o /tmp/install-raven-mux.sh
sh /tmp/install-raven-mux.sh
~/.local/bin/raven-term help

The installer verifies the archive’s SHA-256 checksum and installs both commands under ~/.local/bin. Rerun it to install a newer version. An existing daemon keeps running until you restart its service; finish important processes before doing so.

sudo apt-get update
sudo apt-get install -y build-essential pkg-config libssl-dev \
  protobuf-compiler curl git

# Install rustup if it is not already installed.
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
. "$HOME/.cargo/env"

git clone https://github.com/ThousandBirdsInc/claude-code-iterm-hammerspoon-notifier.git raven
cd raven
cargo build --release --locked --manifest-path rust/raven-mux/Cargo.toml \
  --target-dir target/agent --bin raven-muxd --bin raven-term
mkdir -p "$HOME/.local/bin"
install -m 755 target/agent/release/raven-muxd target/agent/release/raven-term \
  "$HOME/.local/bin/"

A source checkout pins its Rust toolchain. Run the commands as the Linux user who will own the panes. Install your coding agents and their credentials for that same user on the server: processes and files in remote panes belong to the server, not the Mac.

2. Sign the server in

Run this on the server. Open the printed URL in your Mac’s browser, enter the code, and sign in to your Raven account. Leave the command running until it finishes.

~/.local/bin/raven-term teams endpoint --reset
~/.local/bin/raven-term teams login
~/.local/bin/raven-term teams status

This uses the public service. If your shell sets RAVEN_TEAMS_API or RAVEN_TEAMS_HUB for local development, unset those variables first. Each machine keeps its own device key; do not copy your Mac’s ~/.ravendirectory to the server.

In ~/.config/raven-term/config.toml, add these settings or merge them into the existing [remote] section:

[remote]
account = true
bind = "127.0.0.1"

The listener stays on loopback, and the daemon makes an outbound connection to the hosted relay. Leave relay, relay_token, and relay_name unset: those settings are for a separately configured relay.

3. Keep the daemon running

On the server, install a systemd user service. Lingering lets it start at boot and stay up after you disconnect SSH.

mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/raven-muxd.service <<'EOF'
[Unit]
Description=Raven terminal daemon
After=network-online.target

[Service]
Type=simple
ExecStart=%h/.local/bin/raven-muxd
WorkingDirectory=%h
Environment=PATH=%h/.local/bin:%h/.cargo/bin:/usr/local/bin:/usr/bin:/bin
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target
EOF

sudo loginctl enable-linger "$USER"
systemctl --user daemon-reload
systemctl --user enable --now raven-muxd
~/.local/bin/raven-term remote status
journalctl --user -u raven-muxd -n 50 --no-pager

Wait for the log to report that the relay is registered. If the daemon was already running before you signed in, use ~/.local/bin/raven-term remote start. Run one daemon per Raven state directory; use systemctl --user to manage this one. Add any extra agent-tool directories to the service’sPATH if needed.

Your shells survive SSH disconnects and closing the Raven window. Stopping or restarting the daemon ends its running processes; restoring a saved layout does not preserve a process’s memory.

4. Pair your Mac through the hosted relay

On the host, raven-term remote token generates a reusable connection token containing its address, certificate pin, and access credential. When the team relay is available, the token uses that relay automatically. Wait for successful relay registration first. Transfer the token directly over SSH to save it as build-host:

raven_cli="/Applications/Raven.app/Contents/MacOS/raven-term"
ssh build-host '~/.local/bin/raven-term remote token' |
  "$raven_cli" remote add build-host

"$raven_cli" remote list
"$raven_cli" --remote build-host list-panes

Successful list-panes output confirms the connection travels through the relay. SSH is used to transfer the pairing information once; subsequent terminal traffic uses the relay. TLS is pinned to the server’s certificate. Keep --trust-wire off.

The pairing token grants full access to this daemon’s panes. The pipeline keeps it out of your shell history and terminal output, and Raven saves it in ~/.raven/remotes.toml with owner-only permissions. Use this for a host you control. For bounded access to a teammate’s pane, use pane sharing instead.

5. Open the remote panes in Raven

On your Mac, open a window attached to the saved server:

open -n /Applications/Raven.app --args --attach build-host

To show local and remote panes together in one window:

open -n /Applications/Raven.app --args --attach --attach build-host

The bare --attach selects your local daemon; the second selects the paired server. Remote panes are grouped under the saved name. Splits, shells, agents, and file paths in that group run on the server. Use the released Raven.app for these commands:Raven Dev.app has a separate state directory and pairing store.

Reconnect and troubleshoot

• Connection refused or timed out: check systemctl --user status raven-muxd, raven-term remote status, and the service journal on the server. Look for a successful relay registration, and allow outbound TCP 443.
• Sign-in rejected: run ~/.local/bin/raven-term teams login on the server again. In Raven 0.9.5, Settings → General → Account offers Sign in again for rejected credentials and Retry connection for outages. An outage keeps your saved account details.
• The device was revoked: reauthentication registers a new device ID. Restart the remote listener with remote stop followed by remote start, then repeat the Mac pairing step so it uses the new relay address.
• Certificate or token changed: repeat pairing over your trusted SSH connection. Do not disable certificate verification.
• No paired remote named build-host: use the same local OS user and Raven state directory for pairing and opening the window. Check the app path if Raven is installed somewhere other than /Applications.

To remove the saved pairing from this Mac, run "$raven_cli" remote remove build-host. To turn remote access off on the server, set [remote] account = falseand enable = false, then run ~/.local/bin/raven-term remote stop. Removing one client’s saved pairing does not invalidate other copies of its token.