# tunnelto.dev for agents

tunnelto.dev gives a locally running web server a public HTTPS URL
(`https://<subdomain>.tunnelto.dev`). This page is written for coding agents and
automation; the human-facing site is at https://tunnelto.dev.

**If the user asked you to set up tunnelto, follow
[Connect the MCP server](#connect-the-mcp-server) below.** Use the CLI-only
fast path when you can't add MCP servers in this environment.

## Fastest path

```bash
# 1. install (skips if already present)
command -v tunnelto || curl -sL https://tunnelto.dev/install.sh | sh

# 2. (optional) store an access key from https://tunnelto.dev/dashboard
tunnelto set-auth --key <ACCESS_KEY>

# 3. open a tunnel in the background and read the public URL from the log
tunnelto --port 8000 > /tmp/tunnelto.log 2>&1 &
sleep 3 && sed 's/\x1b\[[0-9;]*m//g' /tmp/tunnelto.log \
  | grep -oE 'https://[a-z0-9-]+\.(tunnelto|tunn)\.dev' | head -1
```

The tunnel stays open while the process runs. Kill the process to close it.

`tunn` is a short alias for `tunnelto` (CLI 0.2.0 and later); every example works with either name.

## Connect the MCP server

The MCP server at `https://tunnelto.dev/mcp` (Streamable HTTP, OAuth) manages
the user's tunnelto account: plan and free trial, reserved subdomains, CLI
sign-in, and tunnels. The user signs in once in the browser, which also creates
their tunnelto account; nobody copies an access key by hand.

If the tunnelto tools are already available, skip to
[Test it end to end](#test-it-end-to-end).

**Ask the user to run the setup steps; don't run them yourself.** Adding an MCP
server changes your own client's configuration, which permission systems (for
example Claude Code's auto mode) block. Don't edit config files directly
either. Give the user the steps for their client:

- **Claude Code**:
  1. `! claude mcp add --transport http --scope user tunnelto https://tunnelto.dev/mcp`
     (the `!` prefix runs it in the session so the output shows up in the chat)
  2. `/mcp`, choose `tunnelto`, then Authenticate. The browser sign-in also
     creates the tunnelto account.
  3. If the tools don't appear afterwards, restart Claude Code.
- **Codex**: `codex mcp add tunnelto --url https://tunnelto.dev/mcp`, then
  `codex mcp login tunnelto` to sign in in the browser. If the tools don't
  appear afterwards, start a new Codex session.
- **Grok**: `grok mcp add --transport http tunnelto https://tunnelto.dev/mcp`;
  Grok opens the browser to sign in the first time a tunnelto tool runs.
- **Several agents at once**: `npx add-mcp https://tunnelto.dev/mcp --name tunnelto`
  detects installed agents (Claude Code, Codex, Cursor, VS Code, Grok, and
  others) and writes each one's config; the user still signs in per agent.
- **Cursor, VS Code, the Claude app, or anything else**: send the user to
  https://tunnelto.dev/connect, which has one-click installs for Cursor and
  VS Code and the steps for every other client.

End by asking the user to tell you when they're signed in. When they do, or as
soon as the tunnelto tools show up, continue with the end-to-end test without
waiting to be asked again.

## Test it end to end

Run this once, right after the MCP server is connected, so the user sees a
working tunnel before relying on it:

1. **Account**: call `get_account` and tell the user their plan (free trial
   minutes left, or paid with reserved subdomains).
2. **CLI**: if neither `tunnelto` on `PATH` nor `~/.tunnelto/bin/tunnelto`
   exists, call `get_cli_install_instructions` and run its command. The
   installer does not change `PATH`, and you shouldn't edit shell profiles
   (that is usually blocked too): call the binary by its full path,
   `~/.tunnelto/bin/tunnelto`, and tell the user the one line to add if they
   want it on `PATH`.
3. **CLI sign-in**: if `~/.tunnelto/key.token` doesn't exist, call
   `setup_cli_auth` and run the command it returns.
4. **Demo app**: pick a free local port (check with `ss -ltn` or `lsof -i`),
   write a one-page `index.html` to a temporary directory, and serve it in the
   background, for example
   `python3 -m http.server 8765 --bind 127.0.0.1 --directory <dir>`.
5. **Tunnel**: call `start_tunnel` with that port and `host: "127.0.0.1"`, and
   no subdomain, so the test doesn't use up a reserved name. Run the command it
   returns. Generated URLs come from the CLI key, so only one tunnel without a
   subdomain can run per key at a time: if `start_tunnel` warns that one is
   already open, ask the user whether to stop it or to use one of their
   reserved subdomains for the test instead.
6. **Verify**: `curl` the public URL and check it returns *your demo page*
   (match its text, not just a 200; a 200 with other content means the URL
   belongs to another tunnel). Then call `list_tunnels` with
   `active_only: true` and confirm the tunnel is listed.
7. **Report and clean up**: give the user the public URL and the local inspect
   dashboard URL from the log, then stop the tunnel and the demo server unless
   they want to keep them. Finish with a few example requests from the next
   section.

## What to ask your agent

Once tunnelto is connected, the user can ask in plain language. Examples to
share with them:

- "Give me a public URL for my app on port 3000"
- "Expose localhost:8080 at acme-staging.tunn.dev" (paid plan; reserves the name)
- "I need a Stripe webhook URL that reaches localhost:4242/webhooks"
- "Share my dev server with a teammate"
- "Which tunnels are running?" or "Close the tunnel on port 3000"
- "Reserve the subdomain acme-demo" or "Release acme-demo"
- "Upgrade my tunnelto plan"

## How the tools fit together

Call `get_account` first, then follow the server's instructions:
`get_cli_install_instructions` installs the CLI, `setup_cli_auth` signs it in
with a one-time link (the access key never enters the conversation), and
`start_tunnel` returns the command that opens the tunnel and reads the URL
back. Other tools: `list_subdomains`, `reserve_subdomain`, `release_subdomain`,
`list_tunnels`, `get_payment_link`. When a feature needs the paid plan, the
tools return a checkout link to pass to the user.

The MCP server cannot run commands on the user's machine: you run the commands
its tools return.

## Install the skill

A ready-made skill (SKILL.md) with the full flag reference, recipes, and gotchas
lives at https://tunnelto.dev/skills/tunnelto/SKILL.md.

```bash
# skills CLI (works for Claude Code, Codex, Cursor, and others)
npx skills add tunneltodev/tunnelto

# Claude Code, personal (all projects)
mkdir -p ~/.claude/skills/tunnelto && \
  curl -sL https://tunnelto.dev/skills/tunnelto/SKILL.md -o ~/.claude/skills/tunnelto/SKILL.md

# Claude Code, this project only
mkdir -p .claude/skills/tunnelto && \
  curl -sL https://tunnelto.dev/skills/tunnelto/SKILL.md -o .claude/skills/tunnelto/SKILL.md

# Generic agents directory (Codex, Cursor, and other tools that read .agents/skills)
mkdir -p .agents/skills/tunnelto && \
  curl -sL https://tunnelto.dev/skills/tunnelto/SKILL.md -o .agents/skills/tunnelto/SKILL.md
```

## Facts worth knowing

- All CLI status output is on **stderr**. Merge streams (`2>&1`) before
  grepping for the URL. The output contains ANSI colour codes (`NO_COLOR` is
  not honoured), so strip them first.
- The public URL may be on `tunnelto.dev` or `tunn.dev`; match both.
- Default local port is `8000`; change it with `--port`. Forward to another
  host with `--host`, or to a local HTTPS server with `--use-tls`.
- Without an access key the subdomain is generated and `--subdomain` is
  ignored. Reserved subdomains and teams are part of the paid plan
  ($4 per user per month, up to 20 reserved subdomains and 5 concurrent
  tunnels per user).
- The key is stored in `~/.tunnelto/key.token`. `--key` overrides it for one run.
- A `Local inspect dashboard` URL is printed alongside the public URL; it lists
  every request that passed through the tunnel and is handy for debugging
  webhooks.
- Exit status 1 with `Server terminated connection` means the server closed the
  tunnel (limits, bad key, or a subdomain owned by someone else).

## Command reference

```
tunnelto [FLAGS] [OPTIONS] [SUBCOMMAND]

FLAGS
  -t, --use-tls          forward to https://<host>:<port> instead of http://
  -v, --verbose          debug logging
OPTIONS
  -p, --port <PORT>              local port to forward to         [default: 8000]
  -s, --subdomain <NAME>         requested subdomain (paid plan)
  -k, --key <KEY>                access key for this run
      --host <HOST>              local host to forward to         [default: localhost]
      --dashboard-port <PORT>    fixed port for the inspect dashboard
SUBCOMMANDS
  set-auth --key <KEY>           store the access key in ~/.tunnelto/key.token
```

## Links

- Skill: https://tunnelto.dev/skills/tunnelto/SKILL.md
- MCP server (OAuth): https://tunnelto.dev/mcp, setup for every client: https://tunnelto.dev/connect
- Dashboard (keys, subdomains, team, billing): https://tunnelto.dev/dashboard
- Install script: https://tunnelto.dev/install.sh
- CLI releases: https://github.com/tunneltodev/tunnelto/releases
- Support: support@tunnelto.dev
