OpenCode Relay Server

Secure remote access to your OpenCode instances

The relay infrastructure for OpenCode Anywhere - enabling encrypted tunnels to your AI coding assistant from anywhere in the world.

---

Overview

This repository contains two components:

1. Relay Server - A Go-based WebSocket relay server (deployed on fly.io)
2. Tunnel Client - A CLI tool that runs on your computer to establish secure tunnels

Quick Start

Prerequisites

• OpenCode Anywhere iOS App - Create an account first
• OpenCode installed on your computer

Install via npm

npm install -g @zero469/opencode-tunnel
opencode-tunnel

Requires Node.js 14+. Works on macOS, Linux, and Windows.

What Happens

1. Login - Enter your email/password (account created in iOS app)
2. QR Code - A pairing QR code appears in your terminal
3. Scan - Use the iOS app to scan the QR code
4. Connected - Your computer is now accessible from anywhere!

The tunnel client will:

• Auto-start OpenCode if not running
• Configure auto-start on boot (launchd/systemd/Windows Task Scheduler)
• Maintain persistent connection with automatic reconnection

Architecture

┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│                 │   E2E   │                 │   E2E   │                 │
│    iOS App      │◄───────►│  Relay Server   │◄───────►│  tunnel-client  │
│                 │ Encrypt │   (fly.io)      │ Encrypt │                 │
└─────────────────┘         └─────────────────┘         └────────┬────────┘
                                                                 │
                                                                 │ HTTP
                                                                 ▼
                                                        ┌─────────────────┐
                                                        │ OpenCode Server │
                                                        │  (localhost)    │
                                                        └─────────────────┘

How It Works

1. tunnel-client connects to Relay Server via WebSocket
2. iOS App sends encrypted requests to Relay Server
3. Relay Server forwards encrypted data to tunnel-client
4. tunnel-client decrypts and forwards to local OpenCode
5. Response travels back the same path (encrypted)

Security Model

Layer	Protection
Transport	TLS 1.3 (WSS/HTTPS) between all components
Payload	AES-256-GCM end-to-end encryption
Key Exchange	Encryption key embedded in QR code, never sent to relay
Authentication	JWT tokens + per-device credentials
Zero Knowledge	Relay server only sees encrypted blobs

How E2E Encryption Works

1. tunnel-client generates a random 256-bit AES key during pairing
2. Key is embedded in QR code data (JSON encoded)
3. iOS app scans QR → extracts key → stores locally
4. All subsequent requests/responses are encrypted with this key
5. Relay server forwards encrypted blobs, cannot decrypt

Tunnel Client Usage

# Start tunnel (default)
opencode-tunnel

# Start with custom port
opencode-tunnel -port 8080

# Show status
opencode-tunnel status

# Logout and clear credentials  
opencode-tunnel logout

# Help
opencode-tunnel help

Configuration Files

Located in ~/.opencode-tunnel/:

File	Purpose
auth.json	Login credentials (JWT token, email)
device.json	Device pairing info (subdomain, auth, encryption key)
opencode.json	OpenCode auto-start config

Self-Hosting the Relay Server

Want to run your own relay server? Here's how:

Prerequisites

• Go 1.21+
• A server with public IP (or use Cloudflare Tunnel)

Build & Run

# Clone
git clone https://github.com/zero469/opencode-relay-server.git
cd opencode-relay-server

# Build
go build -o server ./cmd/server

# Run
PORT=8080 JWT_SECRET=your-secret ./server

Environment Variables

Variable	Default	Description
PORT	8080	Server port
JWT_SECRET	(required)	Secret for JWT signing
DATABASE_PATH	./data/relay.db	SQLite database path
SINGLE_USER_MODE	false	Skip email verification

Deploy to fly.io

fly launch
fly secrets set JWT_SECRET=your-secret
fly deploy

Update Tunnel Client

After self-hosting, update the default relay URL:

opencode-tunnel -relay https://your-relay.fly.dev

API Endpoints

Authentication

Method	Endpoint	Description
POST	/api/send-verification	Send email verification code
POST	/api/register	Register new account
POST	/api/login	Login and get JWT
POST	/api/auto-login	Refresh token

Devices

Method	Endpoint	Description
GET	/api/devices	List user's devices
POST	/api/devices	Register new device
GET	/api/devices/{id}	Get device details
PUT	/api/devices/{id}	Update device
DELETE	/api/devices/{id}	Delete device

Pairing

Method	Endpoint	Description
POST	/api/pairing	Create pairing request
GET	/api/pairing/{id}/status	Poll pairing status
POST	/api/pairing/{id}/complete	Complete pairing

Tunnel

Method	Endpoint	Description
GET	/api/tunnel/{subdomain}	WebSocket tunnel connection
GET	/api/events/{subdomain}	SSE event forwarding
ANY	/proxy/*	HTTP proxy to tunnel

Development

Build All Binaries

# Build server
go build -o server ./cmd/server

# Build tunnel client for all platforms
GOOS=darwin GOARCH=arm64 go build -o tunnel-client-darwin-arm64 ./cmd/tunnel-client
GOOS=darwin GOARCH=amd64 go build -o tunnel-client-darwin-amd64 ./cmd/tunnel-client
GOOS=linux GOARCH=amd64 go build -o tunnel-client-linux-amd64 ./cmd/tunnel-client
GOOS=linux GOARCH=arm64 go build -o tunnel-client-linux-arm64 ./cmd/tunnel-client
GOOS=windows GOARCH=amd64 go build -o tunnel-client-windows-amd64.exe ./cmd/tunnel-client

Project Structure

├── cmd/
│   ├── server/          # Relay server entry point
│   └── tunnel-client/   # Tunnel client entry point
├── internal/
│   ├── config/          # Configuration loading
│   ├── database/        # SQLite database layer
│   ├── handlers/        # HTTP handlers
│   ├── middleware/      # Auth middleware
│   ├── models/          # Data models
│   ├── services/        # Business logic
│   └── tunnel/          # WebSocket tunnel management
├── scripts/             # Deployment scripts
└── dist/                # Pre-built binaries

Related Projects

• opencode-anywhere - The iOS app
• OpenCode - The AI coding assistant

License

MIT

Credits

Built to enable secure remote access to OpenCode by SST.