Tailscale VPN Setup

What is Tailscale?

Tailscale is a zero-config VPN solution that creates a secure network between your devices. It’s perfect for accessing your OpenCode Portal remotely without exposing it to the public internet. Key Benefits:

No port forwarding required
Encrypted peer-to-peer connections
Works behind NAT and firewalls
MagicDNS for easy device naming
Free for personal use (up to 100 devices)
Cross-platform (Linux, macOS, Windows, iOS, Android)

Architecture Overview

┌─────────────────┐         ┌──────────────────┐
│  Mobile Device  │         │   VPS/Server     │
│                 │         │                  │
│  Tailscale IP:  │◄────────┤  Tailscale IP:   │
│  100.x.x.2      │  VPN    │  100.x.x.1       │
│                 │         │                  │
│  Browser        │────────►│  Portal:3000     │
└─────────────────┘         │  OpenCode:4000   │
                            └──────────────────┘

Complete Setup Guide

Create Tailscale Account

Go to https://tailscale.com
Click “Get Started” or “Sign Up”
Sign in with your preferred provider:
- GitHub (recommended for developers)
- Google
- Microsoft
- Email

The free personal plan includes up to 100 devices and all essential features.

Install Tailscale on Your Server

SSH into your VPS or server:

ssh user@your-server

Install Tailscale using the official installation script:

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

This script automatically detects your Linux distribution and installs the appropriate package.Manual installation for specific distributions:

Ubuntu/Debian

curl -fsSL https://pkgs.tailscale.com/stable/ubuntu/jammy.noarmor.gpg | sudo tee /usr/share/keyrings/tailscale-archive-keyring.gpg >/dev/null
curl -fsSL https://pkgs.tailscale.com/stable/ubuntu/jammy.tailscale-keyring.list | sudo tee /etc/apt/sources.list.d/tailscale.list
sudo apt-get update
sudo apt-get install tailscale

CentOS/RHEL/Fedora

curl -fsSL https://pkgs.tailscale.com/stable/centos/8/tailscale.repo | sudo tee /etc/yum.repos.d/tailscale.repo
sudo yum install tailscale
sudo systemctl enable --now tailscaled

Arch Linux

sudo pacman -S tailscale
sudo systemctl enable --now tailscaled

Connect Server to Tailscale

Start Tailscale and authenticate:

sudo tailscale up

This command will output a URL like:

To authenticate, visit:
https://login.tailscale.com/a/xxxxxxxxxxxxx

Copy the URL and open it in your browser
Sign in with the same account you created in Step 1
Authorize the device
Optionally give your device a friendly name

Verify connection:

tailscale status

You should see your device listed with a Tailscale IP (100.x.x.x).Get your server’s Tailscale IP:

tailscale ip -4

Install Tailscale on Mobile Device

iOS

Open the App Store
Search for “Tailscale”
Install the official Tailscale app
Open the app
Sign in with the same account
Enable the VPN when prompted

Android

Open Google Play Store
Search for “Tailscale”
Install the official Tailscale app
Open the app
Sign in with the same account
Tap “Connect” to enable VPN

After connecting, you should see all your Tailscale devices in the app, including your server.

Enable MagicDNS (Recommended)

MagicDNS lets you access devices by name instead of IP address.

Go to https://login.tailscale.com/admin/dns
Click “Enable MagicDNS”
Optionally add a custom nameserver if needed

Benefits:

Access server by name: http://my-server:3000 instead of http://100.x.x.1:3000
Names update automatically if IP changes
Easier to remember and manage

Test MagicDNS:On your mobile device (with Tailscale connected):

# Use a terminal app like Termius or iSH
ping my-server-name

Device names are sanitized: spaces become hyphens, special characters removed. Example: “My VPS Server” becomes “my-vps-server”

Configure Firewall (if needed)

If your server has a firewall, you may need to allow Tailscale traffic.UFW (Ubuntu/Debian):

# Tailscale manages its own firewall rules
# Usually no action needed, but ensure UFW allows Tailscale interface
sudo ufw allow in on tailscale0

firewalld (CentOS/RHEL):

sudo firewall-cmd --permanent --add-interface=tailscale0 --zone=trusted
sudo firewall-cmd --reload

Tailscale creates a network interface called tailscale0 and manages its own firewall rules, so usually no additional configuration is needed.

Start Portal for Remote Access

Start OpenCode Portal bound to all interfaces:

cd /path/to/your/project
openportal --hostname 0.0.0.0

The --hostname 0.0.0.0 flag ensures Portal listens on all network interfaces, including the Tailscale interface.Verify it’s running:

openportal list

Access Portal from Mobile

On your mobile device:

Ensure Tailscale VPN is connected (check the app)
Open your mobile browser
Navigate to one of:
- With MagicDNS: http://your-server-name:3000
- With IP: http://100.x.x.1:3000 (use your server’s Tailscale IP)
Bookmark the page for quick access
Optionally add to home screen for app-like experience

You should now see the OpenCode Portal interface and be able to create sessions and chat with the AI.

Advanced Configuration

Subnet Routing

If you want to access other devices on your server’s local network through Tailscale:

# On your server, advertise subnet routes
sudo tailscale up --advertise-routes=192.168.1.0/24

# In Tailscale admin console, approve the routes
# Go to Machines > [Your Server] > Edit route settings > Approve

Exit Node

Use your server as an exit node to route all internet traffic through it:

# On your server
sudo tailscale up --advertise-exit-node

# On mobile device, enable in Tailscale app:
# Settings > Use exit node > Select your server

Access Controls (ACLs)

Restrict which devices can access specific services:

Go to https://login.tailscale.com/admin/acls
Edit the JSON policy file
Example restricting Portal access:

{
  "acls": [
    {
      "action": "accept",
      "src": ["tag:mobile"],
      "dst": ["tag:server:3000,4000"]
    }
  ],
  "tagOwners": {
    "tag:mobile": ["[email protected]"],
    "tag:server": ["[email protected]"]
  }
}

SSH Over Tailscale

Access your server via SSH through Tailscale:

# From any device on your Tailscale network
ssh user@server-name

# Or using Tailscale SSH (managed SSH)
tailscale ssh user@server-name

Enable Tailscale SSH in admin console for managed keys and authentication.

Verification and Testing

Check Tailscale Status

On your server:

# View status and connected peers
tailscale status

# View detailed network info
tailscale netcheck

# Test connectivity to specific device
ping mobile-device-name

Test Portal Access

From your mobile device terminal (using Termius, iSH, or similar):

# Test if server is reachable
ping server-name

# Test if Portal port is open
curl http://server-name:3000

# Check Tailscale connection
tailscale status

Performance Testing

# On server
iperf3 -s

# On mobile (requires iperf3 installed in terminal app)
iperf3 -c server-name

Troubleshooting

Can't connect to Tailscale network

Check:

Is Tailscale running?
```
sudo systemctl status tailscaled
```

Restart Tailscale:

sudo systemctl restart tailscaled
sudo tailscale up

Check firewall isn’t blocking Tailscale:
```
sudo tailscale status
```
Verify you’re using the same Tailscale account on all devices

MagicDNS not resolving device names

Solutions:

Verify MagicDNS is enabled in admin console
Restart Tailscale on the device:
```
sudo systemctl restart tailscaled
```
Try using the IP address instead: tailscale ip -4
Check device name doesn’t have invalid characters
Wait a few minutes for DNS propagation

Can't access Portal through Tailscale

Debug steps:

Verify Portal is running:
```
openportal list
```

Check Portal is bound to 0.0.0.0:

# Should show 0.0.0.0:3000, not 127.0.0.1:3000
netstat -tlnp | grep 3000

Test local access on server:
```
curl http://localhost:3000
```
Test Tailscale access from server itself:
```
curl http://$(tailscale ip -4):3000
```
Check firewall rules
Verify you’re using the correct port

High latency or slow performance

Optimization tips:

Check if you’re using direct connection or relay:

tailscale status
# Look for "direct" vs "relay" in connection type

Enable UPnP/NAT-PMP on your router for direct connections
Try different exit nodes if using exit node feature
Check server resources:
```
htop
```
Run network diagnostics:
```
tailscale netcheck
```

Tailscale disconnects frequently on mobile

iOS fixes:

Settings > Tailscale > Allow unlimited background usage
Disable “Low Power Mode” which can kill VPN connections
Keep Tailscale app updated

Android fixes:

Settings > Apps > Tailscale > Battery > Unrestricted
Disable battery optimization for Tailscale
Settings > Tailscale > Enable “Always-on VPN”

Security Best Practices

While Tailscale is secure by default, follow these practices for maximum security:

Enable Two-Factor Authentication (2FA) on your Tailscale account
Use ACLs to restrict access between devices
Regularly review connected devices in admin console
Remove old devices you no longer use
Keep Tailscale updated on all devices
Use Key Expiry to force periodic re-authentication
Monitor access logs in the admin console
Don’t share your Tailscale account - add users individually if needed

Alternative VPN Solutions

While this guide focuses on Tailscale, you can also use:

WireGuard - More control but requires manual configuration
ZeroTier - Similar to Tailscale with different feature set
Cloudflare Tunnel - Good for HTTP services, different architecture
OpenVPN - Traditional VPN, more complex setup
Twingate - Enterprise alternative to Tailscale

Tailscale is recommended for ease of use and zero-config setup.

Getting Started

Installation

Core Features

CLI Reference

Guides

What is Tailscale?

Architecture Overview

Complete Setup Guide

iOS

Android

Advanced Configuration

Subnet Routing

Exit Node

Access Controls (ACLs)

SSH Over Tailscale

Verification and Testing

Check Tailscale Status

Test Portal Access

Performance Testing

Troubleshooting

Security Best Practices

Alternative VPN Solutions

Next Steps

Build docs developers (and LLMs) love

Getting Started

Installation

Core Features

CLI Reference

Guides

​What is Tailscale?

​Architecture Overview

​Complete Setup Guide

​iOS

​Android

​Advanced Configuration

​Subnet Routing

​Exit Node

​Access Controls (ACLs)

​SSH Over Tailscale

​Verification and Testing

​Check Tailscale Status

​Test Portal Access

​Performance Testing

​Troubleshooting

​Security Best Practices

​Alternative VPN Solutions

​Next Steps

Build docs developers (and LLMs) love

What is Tailscale?

Architecture Overview

Complete Setup Guide

iOS

Android

Advanced Configuration

Subnet Routing

Exit Node

Access Controls (ACLs)

SSH Over Tailscale

Verification and Testing

Check Tailscale Status

Test Portal Access

Performance Testing

Troubleshooting

Security Best Practices

Alternative VPN Solutions

Next Steps