DevAgent Docs

English

简体中文

English

简体中文

Appearance

Remote DevAgent Servers ​

Keep DevAgent running on another computer and connect from your laptop.

A Remote DevAgent Server lets one computer do the work while another computer provides the UI. The server keeps the projects, worktrees, terminals, tabs, provider accounts, and agent sessions. Your laptop connects to that running DevAgent instance.

The easiest setup is the DevAgent desktop app on both computers, connected through Tailscale. You do not need to run devagent serve for this path.

Beta

Remote DevAgent Servers are beta. Keep the server and client on a private network path you control, such as the same Tailscale tailnet or LAN.

What runs where ​

Client computer · DevAgent client
  Shows the UI and sends your input
                 │
                 │ private network route
                 ▼
Server computer · DevAgent server
  Stores repos and worktrees
  Runs terminals and agents

Install and authenticate Codex, Claude Code, OpenCode, git, and any provider CLIs on the server computer. A login on your laptop does not automatically carry over to the server.

On a headless devagent serve host, register managed Claude/Codex accounts from the server shell (the remote client disables Add account):

devagent account add --agent claude
devagent account add --agent codex
devagent account list

Install or refresh agent skills without a Settings UI:

devagent skills install --skill orca-cli --skill orchestration
devagent skills update --all

You need:

  • DevAgent installed and updated on both computers
  • Tailscale installed on both computers
  • Both computers signed in to the same tailnet
  • The server computer awake, online, and running DevAgent

Tailscale gives the server a private address that usually starts with 100.. DevAgent puts that address first in its connection-address picker.

1. Create an access link on the server ​

On the computer that should keep the sessions running:

  1. Open the DevAgent desktop app.
  2. Open Settings → Remote DevAgent Servers.
  3. Under Advertise this app as a server, click New Link.
  4. For Connection address, select the Tailscale address. It usually looks like 100.x.y.z.
  5. Click Generate Access Link.
  6. Copy the link under Pair another DevAgent client.

If the Tailscale address is missing, confirm Tailscale is connected and click the refresh button beside Connection address.

Keep the access link private

The pairing URL grants access to this DevAgent runtime. Treat it like a password and send it only to the client you intend to pair.

2. Add the server on your laptop ​

On the computer you want to use as the client:

  1. Open Settings → Remote DevAgent Servers.
  2. Click Add Server.
  3. Enter a recognizable name, such as Remote Server.
  4. Paste the access link from the server.
  5. Click Add Server.
  6. If the saved server shows Disconnected, click Connect.

Adding a server saves it without forcing every new project onto it. Open Advanced → Active Server only when you want server-routed projects, terminals, provider checks, and browser or mobile handoff to use that server by default.

Use the remote server ​

Once the server shows Connected, select it or one of its projects and use DevAgent normally. Terminals, agent processes, files, worktrees, and session state live on the server computer.

When several paired clients share that server, the sidebar filter can offer Hide other-client workspaces so this device only lists workspaces it created. See Worktrees → Sidebar layout.

That means:

  • agents keep running when the client laptop sleeps or disconnects;
  • the server needs the repository, tools, and credentials used by those agents;
  • the server must stay awake and connected to the tailnet;
  • reconnecting the client returns you to the server-owned state;
  • projects you delete on the server disappear from every paired client's sidebar (no permanent ghost rows).

Access and security ​

DevAgent creates a separate, revocable token for each paired client. The server lists these under Shared Server Access.

  • Click the trash button beside a grant to revoke it. Active clients using that grant are disconnected immediately.
  • Generating another link replaces the previous unused link. Clients that already paired keep their own grants until you revoke them.
  • Keep Tailscale ACLs or grants as narrow as your setup allows.
  • Do not forward the DevAgent port directly to the public internet. Prefer Tailscale, WireGuard, a trusted LAN, SSH forwarding, or an authenticated tunnel.
  • Do not select 127.0.0.1 for another computer. That address only works on the server itself.

Alternative: devagent serve ​

Use devagent serve when the host should run without the desktop window—for example, a headless Linux server or a service-managed VM. For a MacBook or desktop you can leave signed in, the in-app setup above is simpler.

Install DevAgent and its bundled CLI on the server, then run:

devagent serve --pairing-address <server-tailscale-ip-or-hostname>

For example:

devagent serve --pairing-address 100.64.1.20

The command:

  • starts the DevAgent runtime without opening the desktop window;
  • runs in the foreground until you press Ctrl-C;
  • prints the bound endpoint and a runtime pairing URL;
  • uses --pairing-address only for the address clients should dial.

Paste the printed pairing URL into Settings → Remote DevAgent Servers → Add Server on the client.

Add --port 6768 when a firewall, tunnel, or service definition requires a fixed port:

devagent serve --port 6768 --pairing-address 100.64.1.20

Use only one host mode at a time. If the DevAgent desktop app is already sharing that computer, do not start a second devagent serve process for the same setup.

Mobile from a headless server ​

For the DevAgent mobile app, request a mobile-scoped QR code and link:

devagent serve --pairing-address 100.64.1.20 --mobile-pairing

Keep the phone on the same tailnet, open DevAgent Mobile, choose Pair, and scan the terminal QR code or paste the printed link.

Desktop app or devagent serve? ​

Desktop app on the server

devagent serve

Best for

An old laptop, Mac mini, or desktop

A headless Linux box, VM, or managed service

Setup

Settings and buttons

Terminal command and service configuration

Server window

Open

None

Access link

New Link → Generate Access Link

Printed in the terminal

Lifetime

While the desktop app is running

While the foreground process or service is running

Remote DevAgent Server or SSH? ​

Use SSH worktrees when DevAgent on your laptop should own the runtime and use another machine only to run selected worktrees and terminals.

Use a Remote DevAgent Server when the other machine should own the full DevAgent runtime and preserve shared sessions for desktop, browser, mobile, or automation clients.

See Ways to run DevAgent for the full comparison.

Troubleshooting ​

The Tailscale address is not listed ​

On the server, confirm Tailscale is connected, then click the refresh button beside Connection address. Both computers must be signed in to the same tailnet. A Tailscale IPv4 address usually starts with 100..

The server is disconnected ​

Confirm the server computer is awake, DevAgent is still running, and Tailscale shows both devices online. Check your tailnet ACLs or grants if one device cannot reach the other.

Update DevAgent on both computers if the server row reports an incompatible protocol version.

On the server, open Settings → Remote DevAgent Servers → Shared Server Access and revoke that grant. Generate a new link for the intended client.

The server cannot find an agent CLI ​

Install and authenticate that CLI on the server computer. Remote sessions use the server's PATH, home directory, and credentials—not the client's.

devagent serve advertises the wrong address ​

Stop the command and restart it with an address the client can reach:

devagent serve --pairing-address <reachable-tailscale-ip-or-hostname>

Do not use a wildcard address or 127.0.0.1 for a remote client.

Next steps ​

DevAgent Desktop Documentation

© 2026 Clouditera. All rights reserved.