Remote Servers

OpenCode by Alltomatos separates the interface from the server. The desktop app is a client: it can drive a server running on your machine, on another computer in the office, or on a VPS keeping sessions alive 24/7.

Connecting to a server

Settings → Servers → Add server offers several connection types, shown as badges next to each server in the list:

• HTTP — a server reachable at an address (local network or internet).
• SSH tunnel — the app opens and maintains the tunnel by itself, reading the key automatically from ~/.ssh.
• Tailscale — detects an active Tailscale connection and uses the network IP.
• WSL — local Windows Subsystem for Linux environments.

Servers can be renamed at any time — in Settings or from the projects sidebar context menu — and every add-server modal has a standardized display-name field.

OAuth on remote servers

When connecting a provider that requires OAuth on a remote host, paste the callback URL or authorization code in the dedicated field — the app extracts the token and relays it to the remote host automatically.

Running a server on a VPS

OpenCode also runs as a pure server, with no desktop app — ideal for keeping sessions active 24/7 and reaching them from anywhere:

export OPENCODE_SERVER_PASSWORD="a-strong-password-here"
opencode web --hostname 0.0.0.0 --port 4096      # built-in web UI, open in a browser
# or
opencode serve --hostname 0.0.0.0 --port 4096    # API only, for the desktop app or TUI

Then add the address as a remote server in Settings → Servers, or open the URL directly in the browser. The server keeps a persistent task queue, so pending work survives restarts.

The complete guide — systemd, reverse proxy/TLS and security hardening — lives in the repository at docs/vps-hosting.md.

MCP servers

Beyond OpenCode servers, the app manages MCP (Model Context Protocol) servers that give the agent new tools. In Settings → MCP you can:

• Add, edit (env, headers, cwd, timeout) and remove servers.
• Authenticate servers via OAuth directly in the UI.
• Inspect the tools, prompts and resources a connected server exposes.
• Add known servers with one click — Cloudflare, Gmail, Mercado Pago, Context7, GitHub Copilot.
• Open the raw global config (opencode.jsonc) in the system editor.
• Connect an e-mail account through the dedicated MailMCP screen — no manual file editing — and unlock mail tools (send, reply, forward, with attachments) for sessions and routines.

MCP servers reconnect automatically when the app starts.