# 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.

## 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
NO_COLOR=1 tunnelto --port 8000 > /tmp/tunnelto.log 2>&1 &
sleep 3 && grep -oE 'https://[a-z0-9-]+\.tunnelto\.dev' /tmp/tunnelto.log | head -1
```

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

## 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. `NO_COLOR=1` disables ANSI colours.
- 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
- Dashboard (keys, subdomains, team, billing): https://tunnelto.dev/dashboard
- Install script: https://tunnelto.dev/install.sh
- Source (client and server, Rust): https://github.com/tunneltodev/tunnelto
- Support: support@tunnelto.dev