Skip to main content

​
Overview

The device bridge connects your own machine to GAIA. Once a machine is connected, GAIA can run commands on it and reach the local MCP servers you add — the same way it uses any other integration.
  • Run commands and read/write files — the agent runs shell commands on a connected device with the run_on_device tool, which lets it read and write files anywhere the device’s user account can. File access comes automatically with being connected; there is nothing to configure.
  • Local MCP servers — anything you can start with a command (npx, uvx, docker, python) or that already runs at a local URL.
  • One outbound tunnel — the bridge dials out to GAIA; it opens no inbound ports on your machine. Your device is reachable only while the tunnel runs, and you can revoke it anytime from Settings → Devices.
The bridge is separate from self-hosting. You can pair a machine with GAIA Cloud or your own instance — it does not require running GAIA locally.

​
Two ways to connect

There are two ways to connect a machine — pick whichever fits:
  • GAIA desktop app — connect the computer you’re on with one click, no CLI and no pairing code. Works on macOS and Linux.
  • gaia CLI — pair any machine from the terminal. Best for headless servers, Windows (WSL2), and scripted or advanced setups.
The desktop app and the CLI are independent devices. Connecting one never affects the other, and a single machine can run both — each appears separately under Settings → Devices, and revoking one leaves the other online.

​
Connect with the desktop app (macOS and Linux)

The GAIA desktop app can connect the computer it runs on directly — no CLI, no pairing code. It works on macOS and Linux (Windows isn’t supported yet).
1

Open the Devices settings

In the GAIA desktop app, go to Settings → Devices. The This computer card appears at the top (it shows only in the desktop app).
2

Enable on this computer

Click Enable on this computer. The app pairs this machine as its own device from your signed-in session and starts the tunnel — no code to copy. The card’s status chip switches to Online. Once connected, GAIA can run commands and read or write files on this computer via run_on_device — no file setup required.
3

Add MCP servers

Use Add server on the same card to connect a local MCP server, and remove any entry from its row. The toggle on the card keeps the tunnel running or pauses it live.

​
Stay online from the menu bar

A system-tray (menu-bar) item mirrors the device status — online, paused, or not connected — and lets you Connect or Pause the tunnel, open the app, or Quit (which drops the device offline cleanly). Turn on Launch at login from the tray to keep this computer online across restarts.

​
Grant Full Disk Access (macOS only)

On macOS, the OS-protected folders (Downloads, Desktop, Documents, and so on) stay off limits until you grant Full Disk Access to GAIA.app in System Settings → Privacy & Security → Full Disk Access — the app’s shells inherit the grant, so run_on_device can reach those folders. Everything else works as soon as the device is connected.
macOS only. On Linux there is nothing to grant — file access is immediate once the device is connected, bounded only by normal Unix file permissions.

​
Connect with the CLI

The gaia CLI pairs any machine — macOS, Linux, or Windows (WSL2) — from the terminal. Use it for headless servers, non-macOS machines, and scripted or advanced setups.

​
Requirements

  • macOS, Linux, or Windows (WSL2 recommended)
  • Node.js 20+
  • A GAIA account to pair with

​
Install the CLI

The bridge ships with the GAIA CLI (@heygaia/cli). Install it globally with your package manager: Verify it is available:

​
Pair your machine

Pairing links this machine to your GAIA account. You only do it once per machine.
1

Start pairing

Run:
The CLI prints a short code and a link, then waits for approval.
2

Approve the device

Approve the code in either place:
  • In GAIA chat — paste the code into a chat. GAIA shows an approve button for it.
  • In settings — open Settings → Devices (/settings/devices/approve) and enter the code.
Once approved, the CLI confirms the device is paired.
Options for gaia bridge login:

​
Connect a local MCP server

Run the guided wizard and pick what to connect:
The wizard connects either of two kinds of MCP server. If the machine isn’t paired yet, it walks you through pairing first.
Give the wizard the command that launches your server, for example:
Other examples: uvx some-server, docker run -i --rm my/image. The wizard collects any environment variables or secrets the server needs, then starts it and lists its tools to confirm it works before saving.
Point the wizard at a server already listening on your machine, for example http://localhost:3000/mcp. The URL must be loopback (localhost, 127.0.0.1, or ::1). You can add optional request headers such as Authorization.
Secrets you enter (env vars, headers) are stored locally and never leave your machine. After saving, the wizard registers the server with GAIA and offers to start the tunnel right away.
You don’t add files or folders here. Once the device is connected, GAIA can run commands and read or write files on it via run_on_device automatically — bounded only by the device user account’s permissions. On macOS, the OS-protected folders (Downloads, Desktop, Documents, and so on) additionally require granting Full Disk Access to the terminal that runs gaia bridge up (System Settings → Privacy & Security → Full Disk Access); on Linux there is no such prompt.

​
Keep the device online

Your device is online only while the tunnel is running. Start it with:
This starts the outbound tunnel as a background daemon and frees your terminal — the device stays online after you close the shell. Stop it with:
When the tunnel isn’t running, GAIA sees the device as offline. Run gaia bridge ls to check whether it’s currently running.

​
Manage devices and servers

Use the <key> shown by gaia bridge ls when removing a server:
gaia bridge logout only clears local credentials on this machine. To fully revoke a device from your account, remove it in GAIA under Settings → Devices.

​
Command reference

​
Security

  • Outbound-only. The bridge dials out to GAIA. It opens no inbound ports and requires no port forwarding.
  • File access follows the device. When a device is connected, GAIA can run commands and read or write files on it via run_on_device, bounded by the device user account’s permissions (and, on macOS, by Full Disk Access). It has no access at all while the tunnel is down.
  • Secrets stay local. Environment variables and request headers you enter are stored on your machine and are not uploaded.
  • Revoke anytime. Remove a device from Settings → Devices to cut off access immediately.

​
Next Steps

Commands Reference

See all GAIA CLI commands

Installation

Install and upgrade the CLI