tunnelbox · Control the AI agents on your PC from your phone

Core features

One remote, all your agents

A unified remote gateway on top of the CLI / headless agent ecosystem — sessions, streaming, permissions and commands, normalized into one protocol.

svg-connect

Reverse connection, no public IP

The adapter on your PC makes outbound connections only — no public IP, port mapping or tunnel. Any firewall or corporate network just works.

svg-agents

Many agents, one machine

Run opencode, Claude Code, Codex and more side by side. Each pairs and connects independently; switch between them on your phone, even compare agents on the same task.

svg-approve

Approve risky actions on phone

Before bash or file edits run, the permission request is pushed to a card on your phone — allow / deny / always-allow in one tap. Nothing dangerous is auto-approved.

svg-scan

Pair by scanning a QR code

The terminal prints a QR code and pairing code. Use “Scan to pair” in the tunnelbox App to connect instantly; codes are single-use and expire in 10 minutes.

svg-layers

One protocol, invisible backend

Session lists / streaming output / permission approvals / slash commands are all normalized into one protocol — your phone never cares which agent is behind it.

svg-lock

Privacy first

The relay only does stateless forwarding and stores no conversation content. Transport is fully TLS. Privacy-sensitive users can self-host the relay and stay in control.

Supported agents

Every mainstream CLI agent, covered

Each agent maps to an adapter that normalizes its sessions / streaming / permissions into the unified remote protocol — zero awareness for the relay and your phone.

Agent	Adapter	Type	Status
O opencode	In-process plugin (@tunnelbox/opencode)	A	✅ MVP · Implemented
DS DeepSeek Harness (dsh)	Native Cordis plugin (@tunnelbox/dsh-tunnelbox)	B	✅ Implemented
CC Claude Code	claude-agent-sdk bridge (separate process)	B	✅ Implemented
CX Codex	codex app-server bridge (separate process)	B	✅ Implemented
OW OpenClaw	Official Gateway operator WS	B	✅ Implemented · e2e pending
HM Hermes	hermes chat -Q -q oneshot bridge (+ Native plugin)	B	✅ Implemented · experimental
CS Cursor	Cursor CLI agent -p headless (separate process)	B	✅ Implemented · experimental

A In-process plugin · runs inside the agent server process · B CLI / headless bridge · a separate connector process drives the non-interactive mode. Multiple instances of the same type are supported (opencode1 / opencode2 …).

How it works

Reverse connection + stateless relay

A unified remote gateway for the agent ecosystem: your phone connects to the relay, and adapters on your PC connect back — messages flow both ways.

svg-phone

Your phone

Android · iOS App

Connects to the relay over WSS
Browse sessions & streaming output
Send tasks / approve permissions

svg-relay

relay (Go)

Cloud server · self-hostable

Pairing / auth / forwarding
Stateless — no conversation stored
NATS multi-node horizontal scaling

svg-pc

Your PC

Agent adapters

Connect outward (outbound WS)
opencode: in-process plugin
Others: CLI / SDK bridges

Adapters connect out

Reverse connections punch through NAT and firewalls naturally — office networks and dorms work fine, with no public IP or tunnel service.

Relay only forwards

Low cost and easy to scale. Nodes are stateless and reconnect automatically; session data always lives only in your agent’s local storage on the PC.

Pair once, use forever

After the first scan you get a session token and reconnect automatically. With MySQL configured, a relay restart does not require re-pairing either.

Download

Start right now

Download the tunnelbox App from the official website (Android & iOS are both available). Scan the QR code or tap a button below.

Scan to download the App

Android · iOS

tunnelbox App

Native mobile app: scan-to-pair, remote sessions, streaming output, risky-action approvals and push notifications.

Download for Android Download for iOS

Tutorial

Pair in three steps, then take off

Every agent follows the same path: install the adapter on your PC → scan with your phone → go. The setup manual below gives foolproof step-by-step commands for each agent — copy them with one click.

1

Step 1 · Run your agent’s adapter on the PC

Install and run the adapter for your agent (commands in the "Setup manual" below). Once running, the terminal prints a QR code + pairing code.

2

Step 2 · Install & open the tunnelbox App on your phone

Download and install the tunnelbox App (Android & iOS) from the official website, then sign in.

3

Step 3 · Pair by scanning

Tap "Scan to pair" and point it at the terminal QR code to connect automatically — or type the pairing code manually. The agent appears on your home list once paired.

4

Step 4 · Start operating remotely

Open the agent chat page: switch / create sessions via tabs, send prompts, watch streaming output render in real time, approve risky actions on the card, and hit "Stop" whenever you want.

Setup manual for every agent

Pick your agent below and follow the steps one by one — every command has a one-click copy button.

Prerequisites

Recommended environment: macOS / Linux / Windows (WSL)
No separate Node install needed — opencode bundles a Bun runtime and the plugin runs inside it

Install opencode (official)

First install opencode itself (official one-liner for macOS / Linux; on Windows use WSL, or Chocolatey / Scoop):

# macOS / Linux (official one-line installer)
curl -fsSL https://opencode.ai/install | bash

# Windows (PowerShell): Chocolatey / Scoop / WSL
choco install opencode

After install, opencode --version should print a version number.

Installation steps

1Add the npm package to the plugin array in opencode.json (auto-installed on first start)

// opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@tunnelbox/opencode"]
}

Run & pair

2Restart opencode (--print-logs recommended); the plugin connects to the relay and prints a QR code + pairing code. Inside opencode you can also ask to “show phone pairing code” or type /pair anytime to get the pairing code and a scan-able QR right in the chat.

opencode serve --print-logs

✅ You’re done when the terminal shows the [tunnelbox] QR code — scan it with your phone to pair.

Optional config & tips

No config is needed for the official relay. To use your own relay, set the TUNNELBOX_RELAY_URL env var, or pass options.relayUrl via the object form in opencode.json:

// opencode.json (custom relay)
{
  "plugin": [{ "package": "@tunnelbox/opencode", "options": { "relayUrl": "wss://relay.tunnelbox.top" } }]
}

State lives in ~/.config/opencode/remote-state.json. You can run several adapters on one PC — each pairs independently and the phone lets you switch between them with one tap.

Prerequisites

Node.js ≥ 22 (required by the tunnelbox adapter)
A paid Claude plan (Pro / Max / Team) or an Anthropic Console API key

Install Claude Code (official)

First install Claude Code itself (official native installer — auto-updates, no extra runtime needed):

# macOS / Linux / WSL (official native installer)
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

After install, claude --version should work; sign in with a paid Claude account on first launch.

Installation steps

1Install the adapter globally via npm (no repo clone needed)

# no repo clone needed
npm install -g @tunnelbox/claude-code

Run & pair

2Start the adapter (stays running on your PC); the terminal prints a QR code + pairing code. No Claude SDK is needed on your phone.

tunnelbox-claude-code

✅ You’re done when the QR code appears — scan it with your phone.

Optional config & tips

All optional. Common example:

TUNNELBOX_RELAY_URL=wss://relay.tunnelbox.top \
TUNNELBOX_CWD=D:/workspace/project \
TUNNELBOX_CLAUDE_MODE=plan \
tunnelbox-claude-code

Tool approvals are pushed to your phone by default (allow / deny / always-allow). On disconnect or a 120s timeout the request is automatically denied (fail-closed) — nothing is auto-approved. Modes: default / plan / acceptEdits / bypassPermissions.

Prerequisites

Node.js ≥ 22
An OpenAI account (ChatGPT Plus / Pro, or a platform API key), and a Codex CLI that supports the codex app-server subcommand

Install Codex CLI (official)

First install the Codex CLI itself (official installer or npm):

# macOS / Linux (official installer)
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Windows PowerShell
irm https://chatgpt.com/codex/install.ps1 | iex

# or Node: npm install -g @openai/codex
npm install -g @openai/codex

Verify with codex --version, then codex login to sign in. Adapter self-check: tunnelbox-codex --check (confirms codex app-server is available).

Installation steps

1Install the adapter globally via npm (no repo clone needed)

# no repo clone needed
npm install -g @tunnelbox/codex

Run & pair

2Start the adapter (stays running on your PC); the terminal prints a QR code + pairing code.

tunnelbox-codex

✅ You’re done when the QR code appears — scan it with your phone.

Optional config & tips

All optional. Common example:

TUNNELBOX_RELAY_URL=wss://relay.tunnelbox.top \
TUNNELBOX_CODEX_SANDBOX=workspace-write \
tunnelbox-codex

# optional: TUNNELBOX_CODEX_APPSERVER_ARGS="--stdio"

Approvals and choices are native: codex sends tool-approval requests and multiple-choice questions straight to your phone (allow / deny, pick an option), and its reasoning streams live. Disconnect / timeout are auto-denied (fail-closed). What's allowed is still bounded by TUNNELBOX_CODEX_SANDBOX (read-only / workspace-write / danger-full-access).

Prerequisites

Node.js ^22.19 or >=24
A DeepSeek API key (dsh credentials live in $DSH_HOME/.credentials.yaml, default ~/.dsh)

Install DeepSeek Harness (official)

First install dsh itself (DeepSeek’s official npm package; requires Node.js ^22.19 or >=24):

# Install dsh globally (official package)
npm install -g @deepseek-ai/dsh

# or try instantly: npx @deepseek-ai/dsh web

After install, dsh --version should work; on first use configure a DeepSeek API key (stored in $DSH_HOME/.credentials.yaml).

Installation steps

1Install from npm into the dsh profile (one-time, no repo clone needed)

dsh plugin --profile tunnelbox add @tunnelbox/dsh-tunnelbox
dsh --profile tunnelbox --dump-config   # verify the tunnelbox-dsh layer

Run & pair

2Start the harness + plugin; the terminal prints a QR code + pairing code:

dsh --profile tunnelbox

✅ You’re done when the QR code appears. Model / working directory can be set in the profile’s cordis.yml.

Optional config & tips

All optional. Profile config example (cordis.patch.yml):

- id: tunnelbox-dsh
  config:
    relayUrl: 'wss://relay.tunnelbox.top'
    model: 'deepseek-v4-flash'
    cwd: 'D:/workspace/project'

Approvals follow dsh’s approval / sandbox-policy (default workspace-write + ask) — risky actions are pushed to your phone. Run multiple instances with separate DSH_HOME values.

Prerequisites

Node.js ≥ 22.19
A local OpenClaw Gateway is runnable (model config happens during onboard)

Install OpenClaw (official)

First install OpenClaw (official installer) and complete the onboard wizard:

# macOS / Linux (official installer)
curl -fsSL https://openclaw.ai/install.sh | bash

# Windows PowerShell
iwr -useb https://openclaw.ai/install.ps1 | iex

# finish the setup wizard after install
openclaw onboard

You’re ready once openclaw works and the Gateway is running.

Installation steps

1Install the adapter globally via npm (no repo clone needed)

# no repo clone needed
npm install -g @tunnelbox/openclaw

2Approve the first device pairing (one-time)

The first time the adapter connects to your local Gateway it requests device pairing — approve it manually:

openclaw devices list              # note the requestId
openclaw devices approve <requestId>

Run & pair

3Start the adapter (connects to your local Gateway); after the device is approved the terminal prints the tunnelbox QR code:

tunnelbox-openclaw

✅ After approving the device, the QR code appears — scan it with your phone to pair.

Optional config & tips

All optional. Common example:

TUNNELBOX_RELAY_URL=wss://relay.tunnelbox.top \
TUNNELBOX_OPENCLAW_GATEWAY_URL=ws://127.0.0.1:18789 \
tunnelbox-openclaw

Deleting a session archives it (the Gateway has no hard delete). The bootstrap token for first pairing can be set via openclaw configure --section gateway or TUNNELBOX_OPENCLAW_TOKEN.

Prerequisites

Node.js ≥ 22
A Hermes account / model API key (configured during hermes setup)

Install Hermes Agent (official)

First install Hermes Agent (official installer) and finish setup:

# official installer
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

# finish setup after install
hermes setup

You’re ready when hermes chat -Q -q "hi" responds.

Installation steps

1Install the adapter globally via npm (no repo clone needed)

# no repo clone needed
npm install -g @tunnelbox/hermes

Run & pair

2Start the adapter (stays running on your PC); the terminal prints a QR code + pairing code.

tunnelbox-hermes

✅ You’re done when the QR code appears — scan it with your phone.

Optional config & tips

All optional. Common example:

TUNNELBOX_RELAY_URL=wss://relay.tunnelbox.top \
TUNNELBOX_HERMES_MODEL="anthropic/claude-sonnet-4" \
tunnelbox-hermes

Note: this headless adapter does not provide phone approval; dangerous operations are governed by hermes’s own security policy (fail-closed). Sessions continue on the real Hermes session (the id is auto-discovered after the first turn). Interactive-session approval/question flows live in the official Hermes native plugin (native-plugin/).

Prerequisites

Node.js ≥ 22
A Cursor account (headless usage is billed to your Cursor plan)

Install Cursor CLI (official)

First install the Cursor CLI itself (official installer):

# macOS / Linux (official installer)
curl https://cursor.com/install -fsS | bash

# Windows PowerShell
irm 'https://cursor.com/install?win32=true' | iex

You’re ready when agent -p "hello" outputs normally (headless usage is billed by Cursor).

Installation steps

1Install the adapter globally via npm (no repo clone needed)

# no repo clone needed
npm install -g @tunnelbox/cursor

Run & pair

2Start the adapter (stays running on your PC); the terminal prints a QR code + pairing code. Headless usage is billed by Cursor — make sure it’s in your plan.

tunnelbox-cursor

✅ You’re done when the QR code appears — scan it with your phone.

Optional config & tips

All optional. Common example (plan mode + allow file edits):

TUNNELBOX_RELAY_URL=wss://relay.tunnelbox.top \
TUNNELBOX_CURSOR_MODE=plan \
TUNNELBOX_CURSOR_FORCE=1 \
tunnelbox-cursor

Phone approval is not possible (Cursor hooks are IDE / Cloud-agent only; headless agent -p has no external approval relay), and print mode suppresses thinking (no reasoning cards). What runs is decided by permissions allow/deny + --force/--yolo + --sandbox. Read-only by default (no --force: the agent only proposes, it doesn’t edit). Set TUNNELBOX_CURSOR_FORCE=1 to actually edit files. No CLI yet? macOS / Linux: curl https://cursor.com/install -fsS | bash; Windows: irm 'https://cursor.com/install?win32=true' | iex.

Going further: more agents & self-hosting

Per-adapter READMEs:Beyond the manual above, deeper architecture / protocol details live in each adapter’s README under plugin/ in the repo.
Self-host the relay:docker compose up -d deploys the relay in one command (optional MySQL persistence). An nginx.conf template provides reverse-proxy HTTPS; set NATS_URL to scale out to multiple nodes.

GitHub repository → Requirement docs & adapter spec →

FAQ

Frequently asked questions

My PC has no public IP — does it work from an office / dorm network?

Yes. The adapter on your PC only makes outbound WebSocket connections (a reverse connection). No public IP, port forwarding or tunnel needed; it punches through NAT and firewalls, so corporate networks work fine.

My messages pass through the relay — is that safe?

The relay only does stateless forwarding and stores no conversation content. Transport is fully TLS; pairing codes are single-use and expire in 10 minutes; session tokens are stored as SHA-256 hashes. Privacy-sensitive users can self-host the relay so data stays on their own server.

Where is my conversation history stored?

Only in the agent’s local storage on your PC. The app fetches history from your computer in real time when you open a session; it is unreachable while the PC is off or the plugin is offline. The relay does no cloud sync or backup — that is the deliberate privacy-friendly, low-cost trade-off.

Which agents are supported? Can I run several at once?

opencode, Claude Code, Codex, DeepSeek Harness, OpenClaw, Hermes and Cursor are supported, and multiple instances of the same type are allowed (e.g. opencode1 / opencode2). Each pairs and connects independently — switch between them from your phone list, or let different agents run the same task for a side-by-side comparison.

Do dangerous actions always require my approval?

Yes. When tools such as bash or file edits are invoked, the request follows each agent’s native ask / approval model and is pushed to your phone — it only runs after you allow or deny. You may also pick “always allow” for a tool for the current session.

Is it free? Can I self-host / deploy it?

Free and open source (see the LICENSE in the repo). The relay is self-hostable: Docker / docker compose deploys it in one command, with HTTPS via an nginx reverse proxy, MySQL persistence and NATS multi-node scaling. Android / iOS apps are available on the official website.

How is this different from products like AionUi?

tunnelbox is built around remote control from your phone: relay reverse-connection plus native Android / iOS apps, so you can drive several CLI agents on your PC from anywhere. A unified protocol, a stateless relay and self-hosting friendliness make it easy to run and manage many agents on a single machine.

Take your AI agentswith you, everywhere

One remote, all your agents

Reverse connection, no public IP

Many agents, one machine

Approve risky actions on phone

Pair by scanning a QR code

One protocol, invisible backend

Privacy first

Every mainstream CLI agent, covered

Reverse connection + stateless relay

Your phone

relay (Go)

Your PC

Start right now

tunnelbox App

Pair in three steps, then take off

Step 1 · Run your agent’s adapter on the PC

Step 2 · Install & open the tunnelbox App on your phone

Step 3 · Pair by scanning

Step 4 · Start operating remotely

Setup manual for every agent

Prerequisites

Install opencode (official)

Installation steps

Run & pair

Optional config & tips

Prerequisites

Install Claude Code (official)

Installation steps

Run & pair

Optional config & tips

Prerequisites

Install Codex CLI (official)

Installation steps

Run & pair

Optional config & tips

Prerequisites

Install DeepSeek Harness (official)

Installation steps

Run & pair

Optional config & tips

Prerequisites

Install OpenClaw (official)

Installation steps

Run & pair

Optional config & tips

Prerequisites

Install Hermes Agent (official)

Installation steps

Run & pair

Optional config & tips

Prerequisites

Install Cursor CLI (official)

Installation steps

Run & pair

Optional config & tips

Going further: more agents & self-hosting

Frequently asked questions

Put AI in your pocket — go now

Take your AI agents
with you, everywhere