Navigation

Remote Access

Run CamelAGI on a server (Mac mini, VPS, desktop) and connect from any other machine — via terminal or the macOS app.

How it works

CamelAGI’s gateway server exposes HTTP REST + WebSocket APIs. When running on a remote machine, you connect to it from your local machine — the AI agent runs on the server, your terminal or app is just a client.

┌─────────────────┐         ┌──────────────────────┐
│  Your Machine   │  ──→    │  Server (Mac mini)   │
│  (TUI / App)    │  ←──    │  camel serve         │
│                 │  WSS    │  Agent runs here     │
└─────────────────┘         └──────────────────────┘

Option 1: Tailscale (recommended)

Tailscale creates a private encrypted network between your devices. Zero config, no port forwarding needed.

Server setup

On the machine running CamelAGI:

# 1. Install Tailscale
brew install tailscale   # macOS
# or: curl -fsSL https://tailscale.com/install.sh | sh   # Linux

# 2. Enable Tailscale Serve
camel tailscale serve

# 3. Start the gateway
camel serve

The gateway prints a Tailscale URL like https://my-mac-mini.tailnet.ts.net.

Client setup

On your local machine, just install the Tailscale app and sign in to the same tailnet. No CLI needed.

Terminal

# Interactive setup — lists tailnet devices to pick from
camel tailscale link

# Or connect directly
camel tailscale link my-mac-mini.tailnet.ts.net

This opens a full TUI. Commands you give the AI run on the remote machine.

macOS App

  1. Open the Camel app
  2. Switch to Remote in the segmented control at the top
  3. Enter the .ts.net hostname, enable SSL toggle
  4. Click Connect

Serve vs Funnel

Mode Access Security Client requirement
serve Tailnet only (private) Encrypted via Tailscale Tailscale app installed + same tailnet
funnel Public HTTPS Public URL, auth token required Nothing (anyone with URL)

Serve is recommended — private, no public exposure.

camel tailscale serve    # Private (recommended)
camel tailscale funnel   # Public (requires token)

Option 2: Direct connection

For LAN or VPN setups without Tailscale.

Server

# Generate auth token
camel serve --generate-token

# Start with remote access
camel serve --host 0.0.0.0

Client

# TUI
camel connect ws://192.168.1.10:18305 --token <your-token>

# One-shot
CAMELAGI_REMOTE_URL=http://192.168.1.10:18305 CAMELAGI_TOKEN=xxx camel "hello"

macOS App

  1. Switch to Remote
  2. Enter 192.168.1.10:18305 (port auto-added if omitted)
  3. Enter token
  4. Click Connect

Option 3: SSH tunnel

Forward the gateway port over SSH — server stays on localhost, fully secure.

# On your local machine:
ssh -N -L 18305:127.0.0.1:18305 user@server

# Then use CamelAGI as if local:
camel chat

No token needed since traffic stays on localhost.

Monitoring

Watch live server activity from another terminal:

# Local gateway
camel watch

# Remote gateway
camel watch wss://my-mac.tailnet.ts.net --token <token>

Shows real-time events: messages in/out, tool calls, thinking, subagents, retries, errors.

Configuration

In ~/.camelagi/config.yaml:

serve:
  port: 18305              # Gateway port
  host: "127.0.0.1"       # Bind address (use 0.0.0.0 for remote)
  token: "your-secret"    # Auth token (required for remote)
  tailscale: serve         # off | serve | funnel

Environment variables

Variable Purpose
CAMELAGI_TOKEN Auth token (overrides config)
CAMELAGI_REMOTE_URL Remote gateway URL for one-shot mode

Security

  • Token auth: Required when binding to non-localhost. Uses timing-safe comparison.
  • CSRF bypass: Token-authenticated requests skip CSRF checks (not a browser attack vector).
  • Minimal health: Unauthenticated /health returns only { status: "ok" } — no server details.
  • Tailscale Serve: Traffic encrypted end-to-end via WireGuard. No public exposure.
  • Tailscale Funnel: Public HTTPS — always use with an auth token.