Remote Access Patterns

+15 Mana ✨

Introduction

Running an OpenClaw gateway on a remote server or cloud instance requires secure access from your local machine and external services. There are three primary patterns for remote connectivity: SSH tunneling, Tailscale Serve, and traditional VPN. Each approach has distinct trade-offs in terms of setup complexity, security, and performance.

Key Concepts

  • SSH Tunneling: A method of forwarding a local port through an encrypted SSH connection to a remote machine, making a remote gateway appear as if it is running on localhost.
  • Tailscale Serve: A feature of the Tailscale mesh VPN that exposes a local service to your Tailscale network with automatic TLS certificates. This is the preferred approach for OpenClaw.
  • VPN (Virtual Private Network): A traditional network-level solution that places the remote gateway on the same virtual network as your client devices.
  • Port 18789: The default port OpenClaw gateways listen on for API and WebSocket connections.

Real World Context

A development team runs their OpenClaw gateway on a cloud VM. Engineers on different continents need to connect their local nodes and CLI tools to this shared gateway. Some engineers prefer the simplicity of SSH tunneling for quick ad-hoc access, while the team standardizes on Tailscale for persistent access because it handles DNS, TLS, and NAT traversal automatically.

Deep Dive

SSH Tunneling

SSH tunneling is the simplest approach for ad-hoc access. It forwards the gateway's port to your local machine:

bash
ssh -L 18789:localhost:18789 user@remote-server

This command opens an SSH connection to remote-server and forwards local port 18789 to port 18789 on the remote machine. After running this, your local CLI and nodes can connect to localhost:18789 as if the gateway were running locally.

The -L flag specifies local port forwarding. The format is localPort:remoteHost:remotePort. Since the gateway listens on localhost on the remote machine, localhost:18789 is the correct remote target.

SSH tunneling works well for individual developers but has limitations: the tunnel drops when the SSH session ends, it requires SSH access to the server, and each user needs their own tunnel.

Tailscale Serve (Preferred)

Tailscale is the preferred method for persistent remote access. It creates a mesh VPN between your devices with automatic key management, NAT traversal, and DNS:

bash
tailscale serve --bg 18789

This command exposes port 18789 on the current machine to your Tailscale network. Other devices on the same Tailscale network can access the gateway using the machine's Tailscale hostname, such as https://gateway-server.tailnet-name.ts.net.

Tailscale Serve automatically provisions TLS certificates, so connections are encrypted end-to-end. It also handles NAT traversal, meaning it works even when both the server and client are behind firewalls without any port forwarding configuration.

The --bg flag runs the serve in the background. Without it, the command runs in the foreground and stops when you close the terminal.

Tailscale is preferred over SSH tunneling because it provides persistent access, handles multiple users naturally, includes built-in ACLs for access control, and does not require direct SSH access to the server.

Traditional VPN

A traditional VPN (WireGuard, OpenVPN) places the gateway on a shared virtual network:

text
Client (10.0.0.2) ──── VPN ──── Gateway (10.0.0.1:18789)

This approach is appropriate when your organization already operates a VPN and you want to place the gateway on the existing network. It provides network-level security but requires more infrastructure to set up and maintain compared to Tailscale.

Traditional VPNs are best suited for enterprises with existing VPN infrastructure, environments with strict network security policies, and scenarios where all traffic (not just OpenClaw) must traverse the VPN.

When to Use Each

text
SSH Tunneling  → Quick, ad-hoc access for a single developer
Tailscale      → Persistent team access (recommended default)
Traditional VPN → Enterprise environments with existing VPN infra

For most teams, Tailscale provides the best balance of simplicity and security. SSH tunneling is useful for debugging and temporary access. Traditional VPNs are warranted when organizational policy requires them.

Common Pitfalls

  • Exposing port 18789 directly to the public internet: Never bind the gateway to 0.0.0.0:18789 without a reverse proxy or firewall. Always use one of the secure access patterns described above.
  • Forgetting the -L flag direction in SSH tunneling: The format is localPort:remoteHost:remotePort. Reversing the direction with -R creates a remote forward, which is not what you want for accessing a remote gateway.
  • Not running Tailscale Serve with --bg: Without the background flag, the serve process stops when the terminal closes, unexpectedly disconnecting all clients.

Best Practices

  • Default to Tailscale for team setups: It handles TLS, DNS, NAT traversal, and access control with minimal configuration.
  • Use SSH tunneling only for temporary access: It is ideal for debugging but not suitable as a permanent connectivity solution.
  • Restrict gateway binding to localhost: Let the secure access layer (SSH, Tailscale, VPN) handle external exposure rather than binding the gateway to all interfaces.

Summary

  • SSH tunneling forwards port 18789 through an encrypted SSH connection for quick ad-hoc access.
  • Tailscale Serve is the preferred approach, providing persistent access with automatic TLS, NAT traversal, and ACLs.
  • Traditional VPNs are appropriate for enterprises with existing VPN infrastructure.
  • Never expose the gateway port directly to the public internet.
  • Choose the access pattern based on your team size, permanence needs, and existing infrastructure.
✓ Completed