0xmrpeter add905a40c docs: clean up and simplify gitbook documentation
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-01 22:28:37 +07:00

4.8 KiB

Tunneling

What it is and why it matters

When your AI agent spins up a local development server — a React app on port 3000, a FastAPI service on port 8000, a database UI on port 5432 — that server is only reachable from your own machine. The tunnel feature solves this by establishing a secure public URL that proxies traffic to any local port.

You can share the URL with teammates, preview your app on a phone, or let a webhook service reach your local API. No manual port-forwarding or cloud deployment required.

OpenACP also runs an internal file viewer server. When an agent edits a file or produces a diff, the viewer generates a shareable link that renders the content with syntax highlighting (via Monaco editor) or side-by-side diff view.


Providers

OpenACP supports four tunnel providers. The active provider is configured once in ~/.openacp/config.json and applies to all tunnels.

Cloudflare (default, free)

Uses the cloudflared binary to create ephemeral *.trycloudflare.com URLs. No account required. OpenACP installs cloudflared automatically to ~/.openacp/bin/cloudflared if it is not already on your PATH.

Supports an optional custom domain if you have a Cloudflare account with a zone configured.

ngrok

Uses the ngrok binary. Requires ngrok to be installed separately (https://ngrok.com/download). Supports authtoken, domain, and region options.

bore

Uses the bore CLI to tunnel through bore.pub (or a self-hosted bore server). Requires bore to be installed (https://github.com/ekzhang/bore). Supports custom server, port, and secret options.

Tailscale Funnel

Uses tailscale funnel to expose a port over your Tailscale network. Requires Tailscale to be installed and authenticated (https://tailscale.com/download). The provider resolves your Tailscale hostname via tailscale status --json to construct the public URL.


Configuration

Add a tunnel block to ~/.openacp/config.json (see Configuration for the full tunnel config reference):

{
  "tunnel": {
    "enabled": true,
    "provider": "cloudflare",
    "maxUserTunnels": 5,
    "storeTtlMinutes": 60,
    "options": {}
  }
}
Field Default Description
enabled false Enable or disable the tunnel feature. When true, the tunnel auto-starts on server boot.
provider "cloudflare" One of cloudflare, ngrok, bore, tailscale
maxUserTunnels 5 Maximum number of simultaneous user-created tunnels
storeTtlMinutes 60 How long file/diff viewer entries are kept in memory
options {} Provider-specific options (see below)

Provider-specific options

Cloudflare:

{ "options": { "domain": "my-app.example.com" } }

ngrok:

{ "options": { "authtoken": "...", "domain": "my-app.ngrok.app", "region": "eu" } }

bore:

{ "options": { "server": "bore.pub", "port": 2200, "secret": "mysecret" } }

Tailscale:

{ "options": { "bg": true } }

CLI commands

Tunnels can be managed from the terminal:

# Expose a local port
openacp tunnel add 3000 --label my-app

# List active tunnels and their public URLs
openacp tunnel list

# Stop a tunnel by port
openacp tunnel stop 3000

# Stop all user tunnels
openacp tunnel stop-all

Inside Telegram or Discord, if you have the agent integration installed, the agent can run these commands on your behalf — just ask it to "expose port 3000" or "give me a public URL for this Vite app."


File viewer

When an agent reads, edits, or writes a file, OpenACP can generate a clickable link that opens the content in a web-based viewer with syntax highlighting and side-by-side diff view. This is especially useful when reviewing changes from your phone.

The viewer supports dozens of languages including TypeScript, JavaScript, Python, Rust, Go, Java, and many more. Large tool output that does not fit inline in chat is also viewable through these links.

Viewer links expire automatically after the configured storeTtlMinutes (default 60 minutes).


Limits and auto-recovery

  • Each user or session can open up to maxUserTunnels tunnels simultaneously (default 5).
  • When tunnel.enabled is true, the tunnel starts automatically on server boot — no manual start needed.
  • If the tunnel connection drops, OpenACP automatically detects the failure and restarts the tunnel within about 90 seconds.

Security

  • Files outside the session's working directory cannot be viewed — path access is restricted to prevent unauthorized file access.
  • Viewer entries expire automatically and are cleaned up periodically.
  • When connecting apps remotely, openacp remote generates a single-use access code instead of embedding secrets in the URL. See App Connectivity for details.