# Localhost Tunnels for AI Agents: Give Your Agent a Public URL

> How to give an AI coding agent a localhost tunnel it can open, check and close itself, with stable URLs, background mode and spend limits.

- Published: 2026-10-28
- Page: https://www.otterkit.com/blog/localhost-tunnel-for-ai-agents

A localhost tunnel for an AI agent is a public HTTPS URL that forwards to a port on your machine, and the agent opens, uses and closes it without your help. With OtterKit the agent can run `npx otterkit tunnel 3000` in a shell, or call the `tunnel_create` tool over MCP. It gets back a URL it can give to you, a teammate, Stripe or your phone.

## When an agent needs a public URL for your local app

Coding agents like Claude Code and Cursor work on your machine, and so does the app they build. Anything outside your machine can't reach `localhost:3000`. That matters in a few common cases:

- **Previews.** The agent built a page and wants you to check it on your phone, or wants to send a link to a client.
- **Webhook handlers.** Stripe, GitHub or Shopify need a public HTTPS URL to send events to, and the agent needs to see those events reach its handler.
- **OAuth callbacks.** Redirect URIs have to stay the same between runs, or you end up editing the provider's settings every time.
- **Checking its own work.** An agent that can open a URL, wait for a request and read it can show that an integration works. Without that, it can only claim that it does.

In each case the agent needs more than a URL. It needs a URL it can create without an interactive prompt, read back in a format it can parse, and shut down when it's done.

## How localhost tunnels work

A tunnel client runs on your machine and opens an outbound connection to a relay server. The relay gives you a public hostname. When a request reaches that hostname, the relay sends it down the open connection, the client passes it to your local port, and the response goes back the same way. The connection starts from your machine, so you don't have to set up port forwarding on your router or change your firewall.

In OtterKit the CLI provisions the tunnel, charges your credits and connects over a WebSocket ([Tunnels docs](https://www.otterkit.com/docs/tunnels)):

```
$ npx otterkit tunnel 3000
✓ Tunnel provisioned · tunnel-a1b2c3d4
✓ Tunnel ready
URL     https://tunnel-a1b2c3d4.otterkit.app
Target  127.0.0.1:3000
```

Some details that matter when an agent is the one using it:

- **The tunnel needs your machine.** If the laptop sleeps or the process exits, the tunnel stops serving. Billing pauses while the tunnel is disconnected.
- **Traffic is captured by default.** Every request is written with its headers, body, status and duration to `~/.otterkit/requests/<subdomain>.jsonl`, so the agent can read what arrived. Bodies over 64 KB and asset responses are stored as metadata only. `--no-log` turns capture off.
- **You can add a password.** `--auth user:pass` requires HTTP Basic auth, and the check happens on your machine before anything is forwarded. Requests without valid credentials get a 401. The credentials are not sent to or stored by OtterKit's servers.

## Letting an agent create and remove tunnels itself

OtterKit gives agents several ways in. All of them share one login, so run `npx otterkit login` once. On a headless machine, set `OTTERKIT_TOKEN` instead.

### Over MCP

The [MCP server](https://www.otterkit.com/docs/mcp-server) gives the agent tunnels, webhooks, capture history, await and replay as tools, so it doesn't have to run shell commands. For Claude Code:

```
claude mcp add otterkit -- npx otterkit mcp
```

For Cursor and other MCP clients, add `npx otterkit mcp` to the client's MCP config (for example `.cursor/mcp.json`). These tools matter most for tunnels:

- `tunnel_create` exposes a local port on a public URL as a background session, with optional capture and Basic auth.
- `sessions_list` and `session_stop` list and stop sessions. The capture log stays on disk after a stop.
- `requests_list` reads captured requests, filtered by method, path or status.
- `request_await` waits until a matching new request arrives, then returns it.
- `request_replay` sends a captured request to a local target again, with optional edits.

In practice, an agent wiring up Stripe checkout can create a tunnel to port 3000 with the subdomain `shop`, wait for `POST /stripe`, check that the signature is valid, then send a signed `customer.subscription.deleted` event to confirm the cancellation path works too.

### With an agent skill

If your agent works through shell commands, OtterKit also offers an Agent Skill that teaches the agent the CLI, so it knows how to start, inspect and stop tunnels on its own. See the Agent Skill page in the docs for setup. If you run OpenClaw, there's a dedicated [OpenClaw guide](https://www.otterkit.com/docs/openclaw) with a ClawHub skill and plugin.

### Over the HTTP API

For your own agent framework, OtterKit has an HTTP API for provisioning a tunnel, checking its status and deprovisioning it. The docs' HTTP API section covers the requests and responses.

## Running a persistent tunnel in daemon mode

An agent can't keep a foreground process open while it does other work. `--daemon` runs the tunnel in the background. Add `--json` and the command prints machine-readable output:

```
$ npx otterkit tunnel 3000 --daemon --ttl 2h --json
{"subdomain":"tunnel-a1b2c3d4","publicUrl":"https://tunnel-a1b2c3d4.otterkit.app","pid":51423, ...}
```

The agent reads `publicUrl`, uses it and moves on. To clean up:

```
npx otterkit status          # see what's running
npx otterkit stop tunnel-a1b2c3d4
```

`stop` ends the tunnel by name, and the capture log stays on disk for later inspection.

**Set a TTL every time an agent starts a tunnel.** The default is 24h. You can use values like `45m`, `4h` or `3d`, or `never`. When the timer runs out, the server stops the tunnel even if the process is still running. The TTL limits how long a tunnel can run. It doesn't change the hourly price. It's a safety net for the case where an agent forgets, crashes or loses its context halfway through a task.

There's one difference between tunnels and webhook endpoints here. A daemon tunnel ends when its process exits, because nothing else can serve it. A daemon webhook endpoint is answered by OtterKit's servers, so it stays live until its TTL runs out or you stop it. Either way, `otterkit status` and `otterkit stop` manage both.

## Stable URLs and custom domains

By default each tunnel gets a random `tunnel-…` name. That's fine for a quick preview but a problem for webhooks and OAuth, where the URL is saved in someone else's dashboard. Use `--subdomain` to get the same URL on every run:

```
npx otterkit tunnel 3000 --subdomain my-api
# -> https://my-api.otterkit.app, every time
```

The first run reserves the name for your account, and later runs on any machine reuse it. You can reserve up to 10 names, and holding a name is free. Names are 3 to 63 characters: a lowercase letter first, then letters, digits or hyphens. The `subdomains` command lists, reserves and releases names without starting a tunnel.

For a project with several services, list your tunnels and webhooks in `otterkit.toml` and start them all with `otterkit up`.

Custom domains work on webhook endpoints. You point a hostname like `hooks.your-company.com` at an endpoint with one CNAME, and certificates are handled for you. Agents can do the same with the MCP `webhook_domain` tool. For a tunnel, a reserved subdomain is the way to get a stable URL.

### Tunnel or webhook endpoint?

If the sender only delivers events and doesn't need a response from your own code, a [webhook endpoint](https://www.otterkit.com/docs/webhooks) is often a better fit than a tunnel. OtterKit's servers answer it, so Stripe and GitHub still get their 200 while your laptop is closed. Requests are held and replayed into your log when you reconnect. `--deliver` copies each capture to a local server. Use a tunnel when the caller needs your app's real response, as with a browser preview, an OAuth flow or an API under test.

## Agent-native tunnels compared with general-purpose tools

Tools like ngrok and Cloudflare Tunnel are mature and widely used, and a person at a terminal can use any of them. The question is what changes when the agent runs the tunnel. Whatever tool you pick, check these:

1. **Non-interactive start, parseable output.** Can the agent start a background tunnel and get the URL as JSON?
2. **Tool-level access.** Is there an MCP server, so the agent calls typed tools instead of scraping terminal output?
3. **A way to stop it and a built-in auto-stop.** Can the agent list and stop what it started, and does the server enforce an expiry if it doesn't?
4. **Visibility into traffic.** Can the agent read, wait for and replay what reached the URL, so it can check its own work?
5. **Stable names.** Can it get the same URL back across runs and machines?
6. **Limits on spend.** If an agent leaves something running, what's the worst case?

For OtterKit, the last answer is concrete. Tunnels cost 1 credit ($0.01) per connected hour, with the first hour charged up front. No endpoint bills more than 300 credits ($3) in any rolling 30 days. New accounts get 10 free credits. The free Mac app adds local guardrails. It stops tunnels when the Mac sleeps, nudges you about idle ones, and shows projected monthly spend in the menu bar. It also lists every session your agents started, even ones started from the terminal.

## FAQ

**Does the tunnel keep working when my laptop is closed?**
No. A tunnel forwards to your machine, so it pauses while you're disconnected, and its billing pauses too. If you need events captured while you're away, use a webhook endpoint, which OtterKit's servers answer for you.

**Can an agent stop its own tunnel?**
Yes. Over MCP it calls `session_stop`. From the shell it runs `npx otterkit stop <name>`. The HTTP API also has a deprovision call. A TTL ensures the server stops the tunnel even if the agent never does.

**Is it safe to let an agent expose a port?**
A tunnel exposes the whole port, so keep the app's own auth on. For anything sensitive, add `--auth user:pass`. The credentials are checked on your machine and never sent to OtterKit. Use a short `--ttl` for previews.

**Do I need the Mac app?**
No. Everything works from `npx otterkit`, the MCP server and the web console. The app adds a live view, an Expose button next to each listening port, and spend guardrails.

**How do I try it without an account?**
The [Try page](https://www.otterkit.com/try) gives you a live webhook URL in your browser. Tunnels need `npx otterkit login`, which starts you with 10 free credits.
