# Localhost Tunnel

> Exposes a local dev server as a public HTTPS URL on a subdomain you choose (https://my-app.preview.agentsroom.dev), without deploying or installing anything.

- Area: Desktop, mobile and web
- Plans: All plans
- Last checked against the product: 2026-09-08
- Web page: https://agentsroom.dev/docs/localhost-tunnel

## What it does

Exposes a local dev server as a public HTTPS URL on a subdomain you choose (`https://my-app.preview.agentsroom.dev`), without deploying or installing anything. Share work in progress with a colleague or a client, test on your own phone from anywhere, or give a QA agent a live target. WebSocket traffic passes through, so Vite HMR, Next.js fast refresh and the Expo Metro bundler keep working. When you stop the tunnel, visitors see an "offline" page.

## Where to find it

- Inside a project, the room dock: **Preview** ("Expose your local server at a public URL") opens the **Preview Tunnels** modal, with an **Active** tab and a **New Tunnel** tab.
- On the phone: the Preview button in the project header (green with a pulsing dot while a tunnel runs).
- Feature switch: Settings > Features > **Live Preview**.

## How to use it

1. Start your dev server (a dev terminal is the natural place). Open **Preview** > **New Tunnel**.
2. **Select a server**: AgentsRoom scans the open local ports and lists what it detects (Next.js 3000, Vite 5173, Expo 8081...). **Re-scan**, or type a **custom port**.
3. Choose a subdomain (lowercase letters, digits and hyphens; a default is proposed) and an optional label ("Frontend", "API"), then **Start Preview**. The tunnel config is saved with the project, so next time it is one click on **Start**.
4. **Copy URL** or **Open in browser**. **Stop tunnel** when done; the config stays for later. A project can hold several tunnels.
5. Sign-in is required to start a tunnel ("Sign in to start a preview tunnel").

The embedded browser automatically targets a running tunnel when it opens, and the phone opens the tunnel URL in a full-screen web view with back, forward, refresh and open-in-Safari.

## Settings

- `tunnelWsUrl` (global, advanced): address of the tunnel service. Leave the default.
- Feature flag **Live Preview** in Settings > Features (`featureFlags`).

## Agent tools (MCP)

None dedicated. Browser-capable agents reach a running tunnel through `browser_navigate`, and the browser picks the tunnel URL by default.

## Providers

All providers, no difference.

## Mobile

Yes, and it was the first surface of the feature: the Preview button opens a sheet (scan the desktop's ports, pick a server or a custom port, choose a subdomain, start), then the site in a web view. Tunnels started on the desktop before the phone connected appear in the **Active** tab. The desktop must be running: the tunnel is opened from your computer.

## Limits

- Free and Plus: 1 tunnel start per week ("Weekly tunnel limit reached", with the reset countdown). Pro and Team: unlimited. Running tunnels keep running while you upgrade.
- Request body up to 10 MB, 15 s timeout per request, 50 pending requests per tunnel. Binary assets are base64-encoded in transit (about a third more bandwidth), fine for development, not for real traffic.
- One extra round trip through the tunnel server: not for performance benchmarks.
- If the connection drops, the desktop reconnects up to 5 times, 3 s apart, with a heartbeat every 25 s; visitors see the offline page meanwhile.
- A subdomain must be unique across users; "Subdomain already used in this project" means the name is taken here.

## Common questions

- **Is it free?** Yes, with one start per week on the free plan. No bandwidth cap on any plan.
- **Does hot reload work through it?** Yes, WebSockets are passed through.
- **Can several people open the URL at once?** Yes; each request is proxied independently.
- **My dev server sees odd hosts.** It does not: Host, Origin and Referer are rewritten to `localhost:PORT` so Vite, Next and Expo behave as usual.
- **Do I need ngrok or a CLI?** No, everything is built in.

## Related

- [Dev Terminals](https://agentsroom.dev/docs/dev-terminals.md): start the server, then expose it.
- [Browser Automation](https://agentsroom.dev/docs/browser-automation.md): the embedded browser targets a running tunnel.
- [Mobile Companion](https://agentsroom.dev/docs/mobile-companion.md): open the preview from the phone.
- [Plans and Pricing](https://agentsroom.dev/docs/plans-and-pricing.md): the weekly start quota.