Arc OS Docs Open in app →

Local Bridge — Linux Setup

Linux-specific install guide (x64 and arm64). For the general overview, pre-flight checklist, errors, security model and diagnostics, see Local Bridge — Setup Guide.

Total time: ~45 seconds — no Gatekeeper friction.

Pick your architecture

Your machine Click this button in CRM Get this file
Most laptops, desktops, VMs, x86 servers Linux (x64) bridge-linux-x64.tar.gz (~50 MB)
Raspberry Pi, AWS Graviton, ARM servers Linux (arm64) bridge-linux-arm64.tar.gz (~50 MB)

Not sure? Run uname -m in your terminal. x86_64 → pick x64. aarch64 or arm64 → pick arm64.

The steps below are identical for both. Substitute arm64 ↔ x64 in folder/binary names.

1. Download

In CRM: Settings → Integrations → Bridge Setup → 🐧 Linux (x64) (or arm64).

You get bridge-linux-<arch>.tar.gz in ~/Downloads/.

2. Extract and run

cd ~/Downloads
tar -xzf bridge-linux-x64.tar.gz
cd bridge-linux-x64
bash install.sh

Some browsers (Firefox, GNOME Web) auto-extract on download. If you already have a folder, skip the tar line.

🎞️ GIF placeholder — media/bridge/linux-install.gif Shot spec: 15-second terminal recording (asciinema export to GIF) — tar -xzf … → cd → bash install.sh → installer prompts → ✓ Connected.

The installer auto-runs chmod +x on the binary for you.

3. Connect

Before launching, grab two values from CRM:

What Where
Token Settings → Integrations → Bridge Setup → click Copy (JWT, 24h TTL)
Project technical name Sidebar → your project → URL slug (e.g. the lowercase one with hyphens, not the display name)

The bridge then prompts for three values:

Token (paste from CRM):  Ctrl+Shift+V
Project name:             <project>
Server URL [enter for default]:  press ⏎

Q: Why a project name if I have several? One bridge instance binds to one project — the workers from that project read files only from the directory you launched the bridge in (sandboxed). To work with multiple projects, run one bridge per project in its own directory.

Q: Why a Server URL? Just press Enter. The default points to the Arc OS production relay. Custom URL is for self-hosted setups; you don't need to touch it.

If you see ✓ Connected, you're done. Switch to CRM → Bridge Setup and confirm the green dot.

Run in the background (daemonize)

nohup ./bridge-linux-x64 > bridge.log 2>&1 &

A persistent service mode (systemd unit) is on the roadmap — see Phase 23.4.

ripgrep — recommended

The search_files tool falls back to a slow native scan if ripgrep isn't installed. For instant searches:

# Debian / Ubuntu
sudo apt install ripgrep

# Fedora / RHEL
sudo dnf install ripgrep

# Arch
sudo pacman -S ripgrep

What's next