Skip to main content
Let GAIA run commands on your machine and use its local MCP servers, over one outbound tunnel. Once a machine is connected, GAIA runs shell commands on it with the run_on_device tool and reads or writes files the device’s user account can access. The bridge opens no inbound ports. You can pair a machine with GAIA Cloud or your own instance. It does not require self-hosting.

​
Pick a way to connect

The desktop app and CLI are separate devices. Each appears in Settings > Devices, and revoking one leaves the other online.

​
Connect with the desktop app (macOS and Linux)

1

Open Devices

In the desktop app, go to Settings > Devices. The This computer card is at the top.
2

Enable it

Click Enable on this computer. The status chip switches to Online.
3

Add MCP servers (optional)

Use Add server on the same card. The toggle pauses or resumes the tunnel.
The menu-bar item shows the status (online, paused, or not connected). From it you can connect, pause, open the app, or quit. Turn on Launch at login there to stay online across restarts.
On macOS, protected folders like Downloads, Desktop, and Documents need Full Disk Access for GAIA.app. Grant it in System Settings > Privacy & Security > Full Disk Access. Linux needs nothing extra.

​
Connect with the CLI

Needs macOS, Linux, or Windows (WSL2 recommended), and Node.js 20 or later.
1

Install the CLI

2

Pair this machine

The CLI prints a code and a link, then waits.
3

Approve the code

Paste the code into a GAIA chat and click approve, or enter it in Settings > Devices (/settings/devices/approve).
4

Go online

This runs the tunnel as a background daemon. The device stays online after you close the shell.
To stop, run gaia bridge down. GAIA sees the device as offline while the tunnel is down.

​
Add a local MCP server

The wizard walks you through pairing first if needed. It connects either kind of server:
Give it the launch command, like npx -y @modelcontextprotocol/server-everything, uvx some-server, or docker run -i --rm my/image. The wizard asks for any env vars the server needs, then starts it and lists its tools before saving.
Give it a loopback URL like http://localhost:3000/mcp (localhost, 127.0.0.1, or ::1). You can add request headers such as Authorization.
Secrets you enter stay on your machine. After saving, the wizard registers the server with GAIA and offers to start the tunnel.
On macOS, the CLI’s protected-folder access comes from the terminal that runs gaia bridge up. Grant Full Disk Access to that terminal.

​
Commands

gaia bridge logout only clears local credentials. To fully revoke a device, remove it in Settings > Devices.

​
Security

  • Outbound only. No inbound ports, no port forwarding.
  • Access follows the device. GAIA can reach files the device’s user account can, and only while the tunnel is up.
  • Secrets stay local. Env vars and headers are not uploaded.
  • Revoke anytime in Settings > Devices.

​
Next steps

Add MCP integrations

Connect remote MCP servers to GAIA

Desktop app

Install the GAIA desktop app