Skip to main content

Remote Server & Mobile Pairing

The DotAgents desktop app includes a Fastify remote server for mobile clients, operator dashboards, and automation. It is disabled by default for local-only installs; enable it when you want your phone or another client to talk to the desktop agent engine.

What It Enables​

  • Mobile chat over the same desktop agent engine
  • QR-code pairing with the mobile app
  • OpenAI-compatible /v1/chat/completions streaming
  • Agent, skill, knowledge note, loop, MCP, and settings management endpoints
  • Optional operator endpoints for health, logs, Discord, WhatsApp, updater, and tunnel controls
  • Optional Cloudflare Tunnel exposure for remote access

Enable the Server​

  1. Open Settings > Remote Server in the desktop app.
  2. Toggle Remote Server on.
  3. Keep Bind address as 127.0.0.1 for same-machine clients, or switch to 0.0.0.0 only when you intentionally need LAN access.
  4. Keep or rotate the generated API key.
  5. Use the QR code from the desktop settings page to pair mobile.
SettingDefaultNotes
EnabledfalseThe server does not start unless enabled, except explicit QR/headless flows.
Port3210Change if another process uses the port.
Bind address127.0.0.1Use 0.0.0.0 only for LAN/tunnel scenarios.
API keyGenerated locallySent as Authorization: Bearer <key>.
Log levelinfoerror, info, or debug.
CORS origins*Restrict this for exposed deployments.
Terminal QRAuto in headlessUseful for VPS/headless pairing flows.

Pair Mobile​

  1. Enable the desktop remote server.
  2. In the desktop app, open the remote server settings and show the QR code.
  3. In the mobile app, open Connection Settings and scan the QR code.
  4. The QR configures the API base URL and bearer token.

The mobile app then talks to the desktop runtime, so it can use your desktop MCP servers, agents, knowledge notes, loops, and conversations.

API Shape​

DotAgents exposes an OpenAI-compatible run endpoint plus management endpoints:

POST /v1/chat/completions
GET  /v1/models
GET  /v1/agent-profiles
GET  /v1/skills
GET  /v1/knowledge/notes
GET  /v1/loops
GET  /v1/mcp/servers
GET  /v1/operator/health

See the Remote API Reference for endpoint details.

Cloudflare Tunnel​

Use a tunnel only when you need access outside your LAN. DotAgents supports:

  • Quick tunnel — easiest for temporary access.
  • Named tunnel — use cloudflareTunnelId, cloudflareTunnelHostname, and optional credentials path for a stable hostname.

Security guidance:

  • Rotate the remote server API key before sharing a tunnel.
  • Keep CORS origins narrow for non-local deployments.
  • Prefer allowlists for operator devices and messaging integrations.
  • Treat tunnel URLs like credentials.

Troubleshooting​

SymptomFix
Mobile cannot connectConfirm the server is enabled and the URL uses your desktop's reachable IP/hostname.
401 UnauthorizedRe-scan the QR code or rotate/copy the current API key.
Works on desktop but not phoneUse 0.0.0.0 bind for LAN, ensure firewall allows the port, and use a LAN IP instead of localhost.
Tunnel is reachable but API failsCheck API key, CORS origins, and the operator health endpoint.

Next Steps​