npm package: @lemantorus/opencode-tunnel
Description: Beautiful TUI for managing OpenCode web server with tunneling
Author: lemantorus
Latest version: 1.0.0

# OpenCode Tunnel

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux%20%7C%20Windows-blue)]()
[![Mobile](https://img.shields.io/badge/Mobile-Android%20%7C%20iOS-green)]()

Terminal UI for managing [OpenCode](https://github.com/anomalyco/opencode) web server with Cloudflare tunneling. Get a public HTTPS URL to access OpenCode from anywhere, including mobile devices.

> **Note:** This is an unofficial community project and is not affiliated with [OpenCode](https://github.com/anomalyco/opencode) or Anomaly.

<p align="center">
  <img src="images/wokring_opencode_application_with_code.jpg" width="700">
</p>

## Features

- **Terminal UI** - Beautiful interface right in your terminal
- **Cloudflare Quick Tunnel** - Public URL without registration
- **Named Tunnel** - Stable URL for permanent use
- **QR Code** - Scan and connect from mobile
- **SSE Proxy** - Full Server-Sent Events support
- **Voice Input** - Dictate text via Groq Whisper API
- **Cross-platform** - macOS, Linux, Windows
- **Mobile App** - OpenCode Mobile for iOS and Android

## Architecture

```
┌──────────────────┐      ┌──────────────┐      ┌─────────────────────┐
│   OpenCode       │      │   Proxy      │      │   Cloudflare        │
│   Server         │─────▶│   (SSE)      │─────▶│   Quick Tunnel      │
│   Port: 33333    │      │   Port: 33334│      │   .trycloudflare.com│
└──────────────────┘      └──────────────┘      └─────────────────────┘
                                                         │
                         ┌───────────────────────────────┘
                         │
                         ▼
              ┌──────────────────────┐
              │   OpenCode Mobile    │
              │   ┌──────────────┐   │
              │   │  QR Scanner  │   │
              │   │  Voice Input │   │
              │   │  WebView     │   │
              │   └──────────────┘   │
              └──────────────────────┘
```

**How it works:**
1. OpenCode Server starts on port 33333
2. Proxy starts on port 33334 and proxies requests + SSE events
3. Cloudflare Tunnel creates a public HTTPS URL
4. Mobile app scans QR and connects
5. Voice messages are transcribed via Groq Whisper

## Screenshots

### TUI Interface

| Initial State | Port Configuration |
|:-------------:|:------------------:|
| ![Disabled](images/opencodetunnel_disabled.png) | ![Ports](images/ports_screen.png) |

| Configuration | Tunnel Running |
|:-------------:|:--------------:|
| ![Config](images/configure_screen.png) | ![Running](images/tunnel_running.png) |

| QR Code for Mobile |
|:------------------:|
| ![QR](images/all_enabled_QR_received_screen.png) |

### Mobile App

| QR Scanner & Connections | Chats in App |
|:------------------------:|:------------:|
| ![Mobile](images/application_screen_QR_and_table_connections.jpg) | ![Chats](images/chats_in_application.jpg) |

## Requirements

| Component | Version | Installation |
|-----------|---------|--------------|
| Node.js | 18+ | [nodejs.org](https://nodejs.org) |
| OpenCode | latest | `npm i -g opencode-ai` |
| cloudflared | latest | See below |

### Installing cloudflared

**macOS (Homebrew):**
```bash
brew install cloudflared
```

**Linux (Debian/Ubuntu):**
```bash
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o cloudflared
sudo chmod +x cloudflared
sudo mv cloudflared /usr/local/bin/
```

**Linux (Arch):**
```bash
yay -S cloudflared-bin
```

**Windows (PowerShell):**
```powershell
winget install Cloudflare.cloudflared
```

**Windows (Manual):**
1. Download from [GitHub Releases](https://github.com/cloudflare/cloudflared/releases)
2. Extract `cloudflared.exe` to a folder in PATH

## Installation

### From Source

```bash
# Clone the repository
git clone https://github.com/lemantorus/opencode-tunnel.git
cd opencode-tunnel

# Install dependencies
npm install

# Build
npm run build

# Run
npm start
```

### Global Installation (Optional)

```bash
npm link
opencode-tunnel
```

## Usage

### Starting

```bash
npm start
```

On first run, TUI automatically:
1. Starts OpenCode Server on port 33333
2. Starts Proxy on port 33334
3. Creates Cloudflare Quick Tunnel
4. Shows QR code for mobile

### Keyboard Controls

| Key | Action |
|-----|--------|
| `S` | Start/stop OpenCode Server |
| `P` | Start/stop Proxy |
| `T` | Connect/disconnect Tunnel |
| `R` | Start/stop everything |
| `C` | Open configuration |
| `L` | Change ports |
| `Q` | Quit |

### Configuration Screen (C)

In configuration you can set:

- **Tunnel Token** - Token for Named Tunnel (optional)
- **Tunnel Hostname** - Named Tunnel URL (optional)
- **Groq Token** - Token for voice input (optional)
- **Enable Logs** - Logging to `~/.opencode-tunnel/proxy.log`

### Changing Ports (L)

Defaults:
- Server Port: `33333`
- Proxy Port: `33334`

You can change them if ports are occupied.

## Mobile App

### Download

Download the latest version from [GitHub Releases](releases/):

| Platform | File |
|----------|------|
| Android | `opencode-mobile-{version}.apk` |
| iOS | `opencode-mobile-{version}.ipa` |

### Installing Android APK

1. Download APK file
2. Open on your device
3. Allow installation from unknown sources if prompted
4. Install

### App Features

- **QR Scanner** - Scan QR from TUI for quick connection
- **Connection History** - Saved servers with online indicator
- **Voice Input** - Microphone button for dictating messages
- **Navigation** - Back and home buttons for easy navigation

### How to Connect

1. Launch TUI on your computer
2. Wait for tunnel creation and QR display
3. Open OpenCode Mobile
4. Tap "Scan QR"
5. Point camera at QR code
6. Done! You're connected to OpenCode

## Voice Input

Voice input uses **Groq Whisper API** for speech-to-text transcription.

### Getting Groq Token

1. Register at [console.groq.com](https://console.groq.com)
2. Go to **API Keys**
3. Create a new key
4. Copy the token

### Configuration

1. In TUI press `C` for configuration
2. Paste Groq Token
3. Press `Enter` to save

### Usage

1. Connect to server via mobile app
2. A microphone button appears in the text input field
3. Tap to start recording (button turns red)
4. Speak
5. Tap again to stop
6. Text is automatically inserted into the input field

## Named vs Quick Tunnel

### Quick Tunnel (Default)

- Free, no registration
- Randomly generated URL: `https://xxx-xxx-xxx.trycloudflare.com`
- URL changes on each reconnect
- Suitable for temporary use

### Named Tunnel

- Stable URL: `https://your-subdomain.yourdomain.com`
- Requires Cloudflare account
- Configure once

**Setting up Named Tunnel:**

1. Create a tunnel in [Cloudflare Zero Trust](https://one.dash.cloudflare.com/)
2. Copy the tunnel token
3. In TUI press `C`
4. Paste **Tunnel Token**
5. Paste **Tunnel Hostname** (your public URL)
6. Save

## Configuration File

Configuration is stored in `~/.opencode-tunnel/config.json`:

```json
{
  "tunnelToken": "your-cloudflare-tunnel-token",
  "tunnelHostname": "https://your-subdomain.yourdomain.com",
  "groqToken": "your-groq-api-key",
  "serverPort": 33333,
  "proxyPort": 33334,
  "enableLogs": false
}
```

## Logs

When logging is enabled (`enableLogs: true`), log file location:
```
~/.opencode-tunnel/proxy.log
```

Contains:
- Proxy requests
- SSE events
- Errors

## Troubleshooting

### "opencode not found"

```bash
npm i -g opencode-ai
```

### "cloudflared not found"

Install cloudflared (see [Installing cloudflared](#installing-cloudflared))

### "Port already in use"

Change ports via `L` key or kill the process:
```bash
# Find process on port
lsof -i :33333
# Kill process
kill -9 <PID>
```

### QR not scanning

- Make sure tunnel is connected (status "connected")
- Try increasing terminal window size
- Check URL under QR code

### Voice input not working

- Check Groq Token in configuration
- Ensure app has microphone access
- Check internet connection

### Tunnel not connecting

- Check internet connection
- Verify cloudflared is installed and accessible
- For Named Tunnel: verify token

## Development

```bash
# Install dependencies
npm install

# Development mode
npm run dev

# Build
npm run build

# Type check
npx tsc --noEmit
```

## Mobile App Development

See [opencode-mobile/README.md](opencode-mobile/README.md)

```bash
cd opencode-mobile
npm install
npm start
```

## Releasing

To create a new release:

1. Update version in `package.json` and `opencode-mobile/app.json`
2. Create and push a tag:
```bash
git tag v1.0.0
git push origin v1.0.0
```
3. GitHub Actions will automatically build APK and upload to Releases

**Required GitHub Secrets:**
- `EXPO_TOKEN` - Get from [expo.dev/settings/access-tokens](https://expo.dev/settings/access-tokens)

## License

MIT