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
maxUserTunnelstunnels simultaneously (default 5). - When
tunnel.enabledistrue, 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 remotegenerates a single-use access code instead of embedding secrets in the URL. See App Connectivity for details.