Remote Gateway Setup

Run the SimpleClaw Gateway on a remote server (VPS, cloud instance) and connect from your local devices.

Why Run Remotely?

Always-on - Gateway runs 24/7 without tying up your laptop
Centralized - One gateway for all your devices
Resource efficient - Small VPS can handle multiple channels
Device flexibility - Connect from macOS, iOS, Android, web

Architecture

┌─────────────────────────────────────────┐
│            Remote Server (VPS)            │
│                                          │
│  ┌──────────────────────────────────┐  │
│  │      SimpleClaw Gateway        │  │
│  │   ws://127.0.0.1:18789         │  │
│  │                                  │  │
│  │  • Channels (Telegram, etc.)   │  │
│  │  • Agent sessions              │  │
│  │  • Bash tool execution         │  │
│  └──────────────────────────────────┘  │
│                  │                       │
│        Tailscale / SSH Tunnel          │
└─────────────────────────────────────────┘
                  │
         ┌────────┼────────┐
         │               │
    ┌────┴────┐    ┌────┴────┐
    │ macOS App│    │ iOS App │
    │  + Nodes │    │ + Nodes │
    └─────────┘    └─────────┘

Quick Start

Provision Server

Recommended specs:

1-2 CPU cores
2GB RAM
20GB storage
Ubuntu 22.04 or Debian 12

Popular providers: DigitalOcean, Linode, Hetzner, Vultr

Install SimpleClaw on Server

SSH into your server:

ssh user@your-server.example.com

Install Node.js 22+:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

Install SimpleClaw:

npm install -g simpleclaw@latest

Run Onboarding

simpleclaw onboard --install-daemon

This will:

Create config directory
Configure Gateway
Set up systemd service (for Linux)
Start the Gateway

Configure Remote Access

Choose Tailscale or SSH Tunnel for secure access.

Access Methods

Option 1: Tailscale (Recommended)

Tailscale provides secure, zero-config networking.

Install Tailscale on Server

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

Configure Tailscale Serve

Enable Tailscale Serve for Gateway:

simpleclaw config set gateway.tailscale.mode '"serve"' --json
simpleclaw config set gateway.bind '"loopback"' --json

The Gateway will be available at:

https://<hostname>.tailnet.ts.net

Connect from Client

Install Tailscale on your local machine, then:

simpleclaw gateway connect --url wss://<hostname>.tailnet.ts.net

Or use in macOS app:

Open SimpleClaw Preferences
Set Gateway URL: wss://<hostname>.tailnet.ts.net
Click Connect

Option 2: SSH Tunnel

Use SSH port forwarding for secure access.

Create SSH Tunnel

On your local machine:

ssh -L 18789:127.0.0.1:18789 user@your-server.example.com -N

Keep this terminal open.

Connect Locally

The Gateway is now available at ws://127.0.0.1:18789:

simpleclaw agent --message "Hello from remote!"

Persistent Tunnel (Optional)

Set up autossh for automatic reconnection:

sudo apt-get install autossh
autossh -M 0 -L 18789:127.0.0.1:18789 user@your-server.example.com -N

Option 3: Public HTTPS (Advanced)

Expose Gateway with reverse proxy (nginx/caddy) + TLS. Security warning: Only do this with strong authentication enabled.

Install Caddy

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/caddy-stable-archive-keyring.gpg] https://dl.cloudsmith.io/public/caddy/stable/deb/debian any-version main" | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

Configure Caddy

Edit /etc/caddy/Caddyfile:

gateway.yourdomain.com {
  reverse_proxy localhost:18789
}

Reload:

sudo systemctl reload caddy

Enable Password Auth

Required for public access:

simpleclaw config set gateway.auth.mode '"password"' --json
simpleclaw config set gateway.auth.password '"your-strong-password"' --json

Connect

simpleclaw gateway connect --url wss://gateway.yourdomain.com --password your-strong-password

Configuration

Gateway Bind Settings

{
  "gateway": {
    "bind": "loopback",  // Only bind to 127.0.0.1
    "port": 18789,
    "auth": {
      "mode": "password",
      "password": "strong-password-here"
    }
  }
}

Important: Always use "loopback" bind for remote setups. Access via Tailscale/tunnel/reverse proxy.

Tailscale Configuration

{
  "gateway": {
    "tailscale": {
      "mode": "serve",        // or "funnel" for public
      "resetOnExit": true      // Cleanup on shutdown
    },
    "auth": {
      "mode": "tailscale"      // Use Tailscale auth headers
    }
  }
}

Managing the Gateway

Systemd Service (Linux)

After simpleclaw onboard --install-daemon, the Gateway runs as a systemd service.

# Status
sudo systemctl status simpleclaw-gateway

# Restart
sudo systemctl restart simpleclaw-gateway

# Stop
sudo systemctl stop simpleclaw-gateway

# View logs
sudo journalctl -u simpleclaw-gateway -f

Manual Start

Run Gateway manually in tmux/screen:

tmux new -s gateway
simpleclaw gateway run --bind loopback --port 18789
# Detach: Ctrl+B, D

Reattach:

tmux attach -t gateway

Device Nodes

Device nodes (macOS, iOS, Android) can execute device-specific commands when paired:

Pair Device from Server

On the server:

simpleclaw nodes pair --platform macos

This displays a QR code or pairing code.

Scan on Device

macOS App: Preferences → Nodes → Pair Device
iOS App: Settings → Pair Device
Android App: Settings → Pair Device

Verify Pairing

simpleclaw nodes list

You should see your device.

Node Commands

Once paired, the Gateway can invoke device commands:

# Camera snapshot (iOS/Android)
simpleclaw agent --message "Take a photo" --deliver --to whatsapp

# System command (macOS node only)
simpleclaw agent --message "Run 'sw_vers' on my Mac"

# Screen recording (all platforms)
simpleclaw agent --message "Record my screen for 10 seconds"

Security Best Practices

Never expose Gateway without authentication. Always use:

Tailscale Serve (recommended)
SSH tunnels
Password auth for public exposure

Security Checklist

Gateway bind set to loopback
Strong password configured if using public access
Firewall rules limit access to port 18789
SSH key-based auth (disable password SSH)
Tailscale ACLs configured
Regular system updates
Channel allowlists configured
DM policy set to pairing or blocked

Monitoring

Health Checks

# Gateway status
simpleclaw gateway status

# Channel health
simpleclaw channels status --probe

# Resource usage
top -bn1 | grep simpleclaw

Log Monitoring

# Tail Gateway logs
simpleclaw gateway logs --tail 100 --follow

# Filter errors
simpleclaw gateway logs --level error

# Systemd logs
sudo journalctl -u simpleclaw-gateway --since "1 hour ago"

Backups

Important directories to back up:

# Config and credentials
~/.simpleclaw/simpleclaw.json
~/.simpleclaw/credentials/

# Session history
~/.simpleclaw/agents/*/sessions/

# Skills
~/.simpleclaw/workspace/skills/

Backup script:

#!/bin/bash
tar -czf simpleclaw-backup-$(date +%Y%m%d).tar.gz \
  ~/.simpleclaw/simpleclaw.json \
  ~/.simpleclaw/credentials \
  ~/.simpleclaw/agents \
  ~/.simpleclaw/workspace

Upgrading

Upgrade SimpleClaw

npm install -g simpleclaw@latest

Restart Gateway

sudo systemctl restart simpleclaw-gateway

Verify

simpleclaw --version
simpleclaw gateway status

Troubleshooting

Cannot connect to remote Gateway

Verify Gateway is running:

ssh user@server "simpleclaw gateway status"

Check Tailscale status:
```
tailscale status
```

Test SSH tunnel:

ssh -L 18789:127.0.0.1:18789 user@server "curl localhost:18789"

Channels not connecting

Check server logs:

ssh user@server "simpleclaw gateway logs --tail 50"

Verify channel config:

ssh user@server "simpleclaw config get channels"

Test channel authentication:

ssh user@server "simpleclaw channels login --channel telegram"

High latency

Use Tailscale for better routing
Check server location (closer is better)
Monitor server resources:
```
ssh user@server "top"
```

Next Steps

Custom Skills

Add custom tools to your remote Gateway

Webhooks

Trigger agent runs from external services

Multi-Agent Setup

Run multiple specialized agents

Troubleshooting

Common remote setup issues

Documentation Index

​Remote Gateway Setup

​Why Run Remotely?

​Architecture

​Quick Start

​Access Methods

​Option 1: Tailscale (Recommended)

​Option 2: SSH Tunnel

​Option 3: Public HTTPS (Advanced)

​Configuration

​Gateway Bind Settings

​Tailscale Configuration

​Managing the Gateway

​Systemd Service (Linux)

​Manual Start

​Device Nodes

​Node Commands

​Security Best Practices

​Security Checklist

​Monitoring

​Health Checks

​Log Monitoring

​Backups

​Upgrading

​Troubleshooting

​Next Steps

Custom Skills

Webhooks

Multi-Agent Setup

Troubleshooting

Remote Gateway Setup

Why Run Remotely?

Architecture

Quick Start

Access Methods

Option 1: Tailscale (Recommended)

Option 2: SSH Tunnel

Option 3: Public HTTPS (Advanced)

Configuration

Gateway Bind Settings

Tailscale Configuration

Managing the Gateway

Systemd Service (Linux)

Manual Start

Device Nodes

Node Commands

Security Best Practices

Security Checklist

Monitoring

Health Checks

Log Monitoring

Backups

Upgrading

Troubleshooting

Next Steps