0.3.0 • Published 2d agoCLI

@igovet/opencode-tui-tunnel

Licence

MIT

Version

0.3.0

Deps

Size

1.6 MB

Vulns

Weekly

Stars

Summary Dependency Versions

OpenCode TUI Tunnel

Run your opencode terminal sessions anywhere — in a clean browser UI, on desktop or mobile.

OpenCode TUI Tunnel is a web tunnel for opencode terminal sessions. It gives you a browser-accessible workspace where you can launch, view, and manage multiple opencode sessions without being tied to a single terminal window.

It exists to make terminal-first workflows easier to access anywhere: local laptop, remote machine, desktop browser, or phone — while keeping sessions persistent through tmux.

Key Features

Browser terminal — Multi-terminal grid with draggable splitters, resizable panes, keyboard navigation (Ctrl/Cmd+Arrow), context menu, and drag-to-reorder tabs
Dashboard — Modern glass dashboard with Recent Projects hero section, filter chips (All/Local/SSH/Active/Discovered), unified sessions list, compact LaunchBar, and collapsible SSH connections panel
2026 Design System — Dark dev-tool premium visual language with glassmorphism surfaces, Geist + JetBrains Mono typography, soft radius tokens, and full accessibility pass (skip-link, focus-trap, reduced-motion, contrast AA)
12 UI primitives — Reusable component library: Button (4 variants), Card (glass/solid), Dialog (focus-trap), Input, Select, Toggle, Tooltip, Badge, StatusDot, Icon, Toast, ToastProvider — all CSS-token-driven
Global toast system — Non-blocking notifications for errors (auto-dismiss 5s, pause on hover, swipe on mobile, aria-live)
Multi-section Settings — Dedicated settings modal with Notifications, Appearance (reduce motion, font size), Terminal (scrollback, font size), and Keyboard sections
SSH connection management — Glass card list with keyboard navigation, Dialog-based create/edit with segment controls (auth type: Key/Agent, provider: Server/Local)
Mobile-adaptive interface — Floating glass keybar with 44px touch targets, adaptive layouts, reduced-motion and reduced-transparency fallbacks
PWA with install CTA — Full PWA support with install banner (consuming beforeinstallprompt), iOS instructions, update toast with reload, offline-ready
Multi-session tmux management — Launch, attach, kill, and organize multiple concurrent terminal sessions backed by tmux

Use Cases

Developers who want persistent opencode sessions across devices
AI-assisted coding workflows where multiple terminal sessions run in parallel
Homelab / remote workstation users who need secure browser access without opening inbound ports
On-the-go debugging from a phone when you're away from your primary machine

Quick Start

npm install -g @igovet/opencode-tui-tunnel
opencode-tui-tunnel doctor
opencode-tui-tunnel start

Then open the printed URL (default: http://127.0.0.1:4096).

Documentation

Continue below for full docs:

Requirements
Installation
Usage
CLI Reference
2026 UI Redesign
SSH Connections
Cloudflare Tunnel Setup (Zero Trust Authentication)
Changelog

Changelog

See CHANGELOG.md for version history.

Requirements

Node.js >= 20
tmux
opencode

Installation

npm install -g @igovet/opencode-tui-tunnel

Or run directly:

npx @igovet/opencode-tui-tunnel

Installation on macOS and Linux

1) Prerequisites

Node.js >= 20.0.0
- macOS: https://nodejs.org/en/download
- Linux: https://nodejs.org/en/download

tmux

macOS (Homebrew):
```
brew install tmux
```

Debian/Ubuntu:

sudo apt update && sudo apt install -y tmux

Fedora/RHEL (dnf):
```
sudo dnf install -y tmux
```

For Linux: native module build tools

Debian/Ubuntu:

sudo apt update && sudo apt install -y build-essential python3

Fedora/RHEL:

sudo dnf groupinstall -y "Development Tools" && sudo dnf install -y python3

2) Global installation

npm install -g @igovet/opencode-tui-tunnel

The package installs one CLI command:

opencode-tui-tunnel

3) Alternative installation methods

Via npx (without global installation):
```
npx @igovet/opencode-tui-tunnel
```

Via yarn global:

yarn global add @igovet/opencode-tui-tunnel

4) Verification after installation

opencode-tui-tunnel --version
opencode-tui-tunnel doctor

5) Troubleshooting (macOS/Linux)

Permission errors (EACCES) during global npm install
- It is recommended to use Node via nvm or configure a user npm prefix.
- Temporary workaround (less preferred): run with sudo.
Native module build errors
- Make sure python3 and compiler tools are installed (build-essential or Development Tools).
- Check your Node.js version (must be >= 20.0.0).
tmux: command not found
- Install tmux via your package manager and verify the binary is available in PATH.
- Check your environment with: opencode-tui-tunnel doctor.

Usage

Start the server (daemon mode)

opencode-tui-tunnel start

start now launches the service in the background, prints the service URL and PID, and exits the parent process after startup.

Example output:

URL: http://127.0.0.1:4096
PID: 12345

If the service is already running, the command reports the existing URL/PID instead of starting a duplicate process.

PWA Support

@igovet/opencode-tui-tunnel web UI supports Progressive Web App (PWA) behavior on compatible browsers. This lets you install the app-like experience on desktop and mobile while still serving from your local tunnel URL.

What PWA support means in this project

A web app manifest (/manifest.webmanifest) defines app metadata and icons.
A service worker (/sw.js) provides offline-capable caching behavior for app shell/navigation.
On supported platforms, the app can be installed to desktop or home screen and launched in standalone/full-screen style UI.

Benefits

Offline support (service worker): cached app shell can still load when connectivity is intermittent.
Home screen / app launcher icon: installable icon on desktop/mobile launch surfaces.
Full-screen / standalone experience: app opens without standard browser tab chrome on supported platforms.
Push notifications: not currently configured in this project.

Desktop installation

Google Chrome: Menu (⋮) → Install app
Microsoft Edge: Menu (…) → Apps → Install
Mozilla Firefox: install flow is not currently supported; use the app directly in the browser tab.

Mobile installation

iOS Safari: Share → Add to Home Screen
Android Chrome: Menu (⋮) → Add to Home Screen

Platform quick guide

Start the service:
```
opencode-tui-tunnel start
```
Open the printed URL in your platform browser.
Follow the install path above for your browser/device.
Launch from the installed icon (desktop app list or mobile home screen).

CLI Reference

Command summary

Command	Description
`opencode-tui-tunnel --version`	Show CLI version
`opencode-tui-tunnel --help`	Show root help
`opencode-tui-tunnel start [--host <host>] [--port <port>] [--no-open]`	Start the tunnel service in daemon mode
`opencode-tui-tunnel autostart on [--host <host>] [--port <port>] [--no-open]`	Enable autostart and start service immediately
`opencode-tui-tunnel autostart off`	Disable autostart and remove managed service
`opencode-tui-tunnel status`	Show tunnel service status
`opencode-tui-tunnel sessions list [--json]`	List running sessions
`opencode-tui-tunnel sessions kill <id>`	Terminate a running session
`opencode-tui-tunnel config get [key]`	Print full config or a specific key
`opencode-tui-tunnel config set <key> <value>`	Update a config key
`opencode-tui-tunnel config path`	Print config file path
`opencode-tui-tunnel doctor`	Run environment diagnostics

Root command

Syntax

opencode-tui-tunnel --version
opencode-tui-tunnel --help

Options

Option	Type	Default	Description
`--version`	boolean	`false`	Print CLI version and exit
`--help`	boolean	`false`	Print command help and exit

Examples

opencode-tui-tunnel --version
opencode-tui-tunnel --help

`start`

Syntax

opencode-tui-tunnel start [--host <host>] [--port <port>] [--no-open]

Start the tunnel service in daemon mode.

Flags

Flag	Type	Default	Description
`--host <host>`	string	`config.server.host` (`127.0.0.1`)	Host interface to bind
`--port <port>`	number (`1-65535`)	`config.server.port` (`4096`)	TCP port to bind
`--no-open`	boolean	`false`	Disable automatic browser opening

Notes

If the service is already running, the command reports the existing URL/PID instead of starting a second process.

Examples

opencode-tui-tunnel start
opencode-tui-tunnel start --port 4300
opencode-tui-tunnel start --host 0.0.0.0 --port 4300 --no-open

`autostart`

`autostart on`

Syntax

opencode-tui-tunnel autostart on [--host <host>] [--port <port>] [--no-open]

Enable autostart and start the managed service immediately.

Flags

Flag	Type	Default	Description
`--host <host>`	string	`config.server.host` (`127.0.0.1`)	Host interface to pass to managed start command
`--port <port>`	number (`1-65535`)	`config.server.port` (`4096`)	Port to pass to managed start command
`--no-open`	boolean	`false`	Disable automatic browser opening in managed start command

Notes

Uses the same runtime flags and validation rules as start.
Running autostart on again replaces the existing managed service definition.
Platform support:
- Linux: user systemd service
- macOS: user LaunchAgent

Examples

opencode-tui-tunnel autostart on
opencode-tui-tunnel autostart on --host 0.0.0.0 --port 4300 --no-open

`autostart off`

Syntax

opencode-tui-tunnel autostart off

Disable autostart and remove the managed service definition.

Examples

opencode-tui-tunnel autostart off

`status`

Syntax

opencode-tui-tunnel status

Show tunnel service status.

Examples

opencode-tui-tunnel status

`sessions`

`sessions list`

Syntax

opencode-tui-tunnel sessions list [--json]

List running sessions.

Flags

Flag	Type	Default	Description
`--json`	boolean	`false`	Print JSON output instead of table output

Examples

opencode-tui-tunnel sessions list
opencode-tui-tunnel sessions list --json

`sessions kill`

Syntax

opencode-tui-tunnel sessions kill <id>

Terminate a running session.

Arguments

Argument	Type	Required	Description
`<id>`	string	yes	Session ID to terminate

Examples

opencode-tui-tunnel sessions kill 12345678

`config`

`config get`

Syntax

opencode-tui-tunnel config get [key]

Get full config or a specific key (dot notation).

Arguments

Argument	Type	Required	Description
`[key]`	string	no	Dot-notation config key (for example `server.port`)

Examples

opencode-tui-tunnel config get
opencode-tui-tunnel config get server.port
opencode-tui-tunnel config get updates

`config set`

Syntax

opencode-tui-tunnel config set <key> <value>

Set a config key. Values support string, number, and boolean input.

Arguments

Argument	Type	Required	Description
`<key>`	string	yes	Dot-notation config key
`<value>`	string \| number \| boolean	yes	Value to store (`true`/`false` => boolean, numeric text => number, otherwise string)

Examples

opencode-tui-tunnel config set server.port 4300
opencode-tui-tunnel config set server.host 0.0.0.0
opencode-tui-tunnel config set server.openBrowserOnStart false

`config path`

Syntax

opencode-tui-tunnel config path

Print config file path.

Examples

opencode-tui-tunnel config path

`doctor`

Syntax

opencode-tui-tunnel doctor

Run environment diagnostics.

Checks

Node.js version (required: >=20)
tmux availability
opencode availability in PATH
Config directory availability/writability
Packaged web assets (dist/web/index.html)

Examples

opencode-tui-tunnel doctor

How it works

Sessions are managed by tmux — sessions survive browser refreshes and server restarts. The web UI shows all active opencode sessions. Click to connect, or launch new sessions in any project directory.

On service start, the app also checks for package updates in the background. For global npm installs, it can apply updates automatically in a detached worker. Updated code is used on the next restart of the service/process.

Mobile support

Full mobile terminal support with custom key bar (Esc, Tab, Ctrl, arrows, etc.).

Configuration

Config is stored at ~/.config/opencode-tui-tunnel/config.json.

Key settings:

server.port — default: 4096
paths.allowedRoots — directories where new sessions can be launched
sessions.maxConcurrent — max concurrent sessions (default: 8)

2026 UI Redesign

The visual interface has been fully redesigned with a "dark dev-tool premium" aesthetic inspired by tools like Linear, Warp, and Arc.

Design System

Colors: Deep #05060a base with glass surfaces (backdrop-filter: blur(12-20px) + subtle 1px border), accent-blue highlights, and gradient accents
Typography: Geist for UI text, JetBrains Mono for terminal content — loaded via non-blocking preconnects
Spacing/Radius: Soft radius tokens (4px/6px/8px) for cards and dialogs; 0px radius for terminal panes for a crisp edge
Zero hardcoded hex policy — all colors, spacing, and typography reference CSS custom properties from a centralized design token system

Dashboard

The main landing page (SessionList) has been redesigned from scratch:

Recent Projects hero — Full-width card grid showing the most recent sessions with one-click "Resume" buttons, backend badges, and relative timestamps
Filter chips — All / Local / SSH / Active / Discovered filter buttons to narrow the session list
Unified sessions list — Merged view of local, SSH, and auto-discovered sessions with consistent row structure (status dot, title, path, backend badge, running time, "Open" action)
Compact LaunchBar — A streamlined command bar with path autocomplete (ARIA combobox), backend selector, and "Run session" button
Collapsible SSH panel — SSH connections section collapsed by default; expand to see connection cards with keyboard navigation

Workspace & Multi-Terminal Grid

The workspace view (WorkspaceView) powers the multi-terminal experience:

Chrome-style tabs — Compact 30px pill tabs with close-on-hover, circular "+" button inside tab strip, drag-to-reorder, right-click context menu (Close / Close others / Close right / Move left / Move right)
Terminal panes — Slim 28px chrome header with pane title, status dot, backend badge, zoom dropdown; active pane gets glow ring; inactive chrome dims while xterm stays full brightness
Draggable splitters — Pointer Events-based drag-resize with 15% minimum pane width for reliable resizing
Keyboard navigation — Ctrl/Cmd+ArrowLeft/Right for pane switching (capture-phase to override xterm word-jump)

Components & Primitives

12 reusable UI primitives live in web/src/components/ui/:

Button, Card, Dialog, Input, Select, Toggle, Tooltip, Icon, Badge, StatusDot, Toast, ToastProvider

All components use var(--*) design tokens and follow the zero-hardcoded-hex policy.

Accessibility

Skip-link as first focusable element
Focus-trap in all dialog-based modals
ARIA combobox on PathAutocomplete
WCAG AA contrast on all text (4.5:1 minimum)
prefers-reduced-motion disables hover/active transforms
prefers-reduced-transparency reduces glass blur

Push Notifications & Toasts

Global ToastProvider renders system-style toasts for API errors, session events, and PWA updates
Auto-dismiss after 5s, pause on hover, swipe-to-dismiss on mobile
Push notifications via Web Push API (VAPID) for session activity when browser is backgrounded

SSH Connections

OpenCode TUI Tunnel supports connecting to remote servers via SSH, allowing you to launch and manage opencode sessions on remote machines directly from the browser UI.

Setting up an SSH connection

Open the web UI and switch to the SSH tab.
Click + NEW CONNECTION to open the connection modal.
Fill in the required fields:
- Name — A friendly label for this connection (e.g., "Home Server")
- Host — The SSH server hostname or IP address
- Port — SSH port (default: 22)
- Username — Your SSH login username
- Authentication — Choose between:
  - SSH key — Select a private key file (supports encrypted keys with passphrase)
  - SSH agent — Use your system's running SSH agent
Configure opencode settings:
- Provider — local (run opencode on the remote server) or server (use the remote server's opencode installation)
- Command — Optional custom opencode launch command
Click Save to store the connection.

Using SSH connections

Launch remote sessions: Select an SSH connection from the dropdown and enter a project path to start an opencode session on the remote server.
Remote tmux discovery: The SSH tab shows all running tmux sessions on the remote server. Click Attach to connect to any existing session.
Manage connections: Use the connection list to edit, test, or delete saved SSH connections.

Secure remote browser access to your local TUI sessions
No public inbound port exposure
Works well with Cloudflare Zero Trust Access policies

2) Prerequisites

A Cloudflare account
A domain managed in Cloudflare DNS
Cloudflare Zero Trust enabled for your account/team
opencode-tui-tunnel running locally (default http://127.0.0.1:4096)

3) Install `cloudflared` and authenticate

Install cloudflared (pick your platform package from Cloudflare docs):

https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/

Authenticate the CLI with your Cloudflare account:

cloudflared tunnel login

This opens a browser to authorize cloudflared for your Cloudflare zone.

4) Create and route a tunnel

Create a named tunnel:

cloudflared tunnel create opencode-tui-tunnel

Route a public hostname to the tunnel (example hostname):

cloudflared tunnel route dns opencode-tui-tunnel tunnel.example.com

5) Configure Zero Trust authentication

Open Cloudflare Dashboard → Zero Trust → Access → Applications.
Click Add an application and choose Self-hosted.
Set the application domain to your tunnel hostname (for example tunnel.example.com).
Create an Access policy (for example, allow specific emails/groups).
In login methods, enable:
- your SSO IdP (Google, GitHub, Okta, Azure AD, etc.), and/or
- One-time PIN.

Note: Cloudflare Access does not provide a standalone local username/password database. "Password authentication" is typically handled by your configured IdP login flow, or by One-time PIN.

6) Example `cloudflared` config

Create ~/.cloudflared/config.yml:

tunnel: <TUNNEL_UUID>
credentials-file: /home/<user>/.cloudflared/<TUNNEL_UUID>.json

ingress:
  - hostname: tunnel.example.com
    service: http://localhost:4096
  - service: http_status:404

Run the tunnel:

cloudflared tunnel run opencode-tui-tunnel

7) Test the setup

Start the local service:
```
opencode-tui-tunnel start
```
Start cloudflared (if not already running).
Open https://tunnel.example.com in a browser.
Confirm you are prompted by Cloudflare Access before the app loads.
Sign in via your configured method (SSO or One-time PIN) and verify the TUI page loads.

8) Troubleshooting

502 / connection errors from Cloudflare
- Verify opencode-tui-tunnel is running on port 4096.
- Check service: http://localhost:4096 in config.yml.
Hostname does not resolve or route correctly
- Re-run cloudflared tunnel route dns ... and verify DNS record exists in Cloudflare.
- Allow time for DNS propagation.
Access login prompt not shown
- Verify the Zero Trust Access app domain exactly matches the tunnel hostname.
- Confirm policy is active and not bypassed by broader rules.
Authentication denied / login loop
- Confirm your user/group/email matches the Access policy allow rules.
- Confirm the configured IdP is healthy and enabled.
cloudflared credentials or tunnel not found
- Re-run cloudflared tunnel login.
- Check that the tunnel name/UUID in config.yml is correct.