# easy tunnels for dev and prod.

`tnl` is in private beta. [email chase@tnl.dev for access](mailto:chase@tnl.dev?subject=tnl.dev%20beta%20access&body=I'd%20like%20to%20try%20https%3A%2F%2Ftnl.dev.%20My%20email%20is%3A).

`tnl` helps you connect to local and/or private services through end-to-end encrypted tunnels. It's like if Tailscale and Cloudflare Tunnel had a baby. And that baby came with a great devex.

## in dev

`tnl` gives every Git worktree its own unique HTTPS URL. Traffic stays encrypted from the browser to your laptop.

## in prod

Connect to your services from anywhere (laptop, CI, etc.).

## start developing

First, install the package with pnpm and initialize your project:

**pnpm**

```bash
pnpm add -D @tnldotdev/tnl
pnpm exec tnl init
pnpm exec tnl auth login
```

**npm**

```bash
npm install -D @tnldotdev/tnl
npx tnl init
npx tnl auth login
```

**bun**

```bash
bun add -D @tnldotdev/tnl
bunx tnl init
bunx tnl auth login
```

For example, with Vite, `pnpm exec tnl init` adds `tnl()` alongside your existing plugins:

```ts
// vite.config.ts
import { defineConfig } from "vite";
import tnl from "@tnldotdev/tnl/vite";

export default defineConfig({
  plugins: [tnl()],
});
```

Start your app (e.g. with `vite dev`) and get its URL. By default, any visitor needs to sign in or have a share link. Hot reloading, WebSockets, SSE, and streaming responses are all supported.

Already have an app listening on port 3000? Run `pnpm exec tnl publish 3000`.

See [the project README](https://github.com/tnldotdev/tnl#start-developing).

## run worktrees side by side

Once your `tnl` setup is committed to Git, you can leave the app running in your main checkout, and in another terminal, create a worktree and start the app there too:

```bash
git worktree add ../perf
cd ../perf
pnpm install --frozen-lockfile
pnpm dev
```

```text
┌──[ one repo, two worktrees ]─────────────────────────────────────────────┐
│                                                                          │
│                              your browser                                │
│                                    |                                     │
│                          https://*.example.com                           │
│                       (tnl.dev or your subdomain)                        │
│                                    v                                     │
│                               tnl ingress                                │
│                          (hosted/self-hosted)                            │
│                                    |                                     │
│                 +------------------+------------------+                  │
│                 |                                     |                  │
│            direct UDP                             tnl relay              │
│         (when possible)                           (fallback)             │
│                 |                                     |                  │
│                 +------------------+------------------+                  │
│                                    |                                     │
│ +----------------------------------v----------------------------------+  │
│ |                             your laptop                             |  │
│ |                                  |                                  |  │
│ |                +-----------------+----------------+                 |  │
│ |                v                                  v                 |  │
│ |       tnl (main checkout)                tnl (perf worktree)         | │
│ |       app-demo.example.com            app-demo-perf.example.com      | │
│ |                |                                  |                 |  │
│ |                v                                  v                 |  │
│ |         localhost:5173                     localhost:5174            | │
│ +---------------------------------------------------------------------+  │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘
```

Vite and Next.js can choose another port when the preferred one is taken, and `tnl` will publish the port they actually open. Restarting either checkout reuses its URL.

## share it and get feedback

You can leave inline feedback in your app for your agent to review. Or, send someone on your team a link:

```bash
pnpm exec tnl share link create app-demo.example.com \
  --expires-in 7d
```

The link expires after a week and can be revoked early. Similar to how Vercel comments work, reviewers can leave inline feedback:

```text
┌──[ feedback without a deployment ]───────────────────────────┐
│                                                              │
│ share link -> your app -> click an element -> leave feedback │
│                                                              │
└──────────────────────────────────────────────────────────────┘
```

```bash
pnpm exec tnl feedback list
```

Then you (or your agent) can use `pnpm exec tnl feedback list` to read feedback from the CLI.

## register your callbacks once

To add OAuth or webhook support, add the following to your config:

```ts
export default defineConfig({
  // ...existing configuration
  oauth: true,
  // and/or
  webhooks: {
    payments: {
      service: "app",
      path: "/webhooks/stripe",
      provider: "stripe",
    },
  },
});
```

The OAuth and webhook URLs do not change when you work across multiple checkouts. They "just work" across all your worktrees. OAuth automatically returns the browser to the worktree that started login:

```text
┌──[ one OAuth callback ]──────────────────────────────────────────────────┐
│                                                                          │
│                    https://app-demo-perf.example.com                     │
│                                    |                                     │
│                                    | start login                         │
│                                    v                                     │
│                                  GitHub                                  │
│                                    |                                     │
│                                    v                                     │
│ +--[ oauth callback url ]---------------------------------------------+  │
│ |             https://oauth-demo.example.com/auth/callback             | │
│ +---------------------------------------------------------------------+  │
│                                    |                                     │
│                                    | redirect browser                    │
│                                    v                                     │
│                    https://app-demo-perf.example.com                     │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘
```

Or, for webhooks, the same event fans out to all running worktrees:

```text
┌──[ one webhook, every worktree ]─────────────────────────────────────────┐
│                                                                          │
│                          webhook (e.g. Stripe)                           │
│                                    |                                     │
│                                    v                                     │
│ +--[ webhook url ]----------------------------------------------------+  │
│ |            https://hooks-demo.example.com/webhooks/stripe            | │
│ +---------------------------------------------------------------------+  │
│                                    |                                     │
│                        +-----------+-----------+                         │
│                        |                       |                         │
│                        v                       v                         │
│                  main checkout            perf worktree                  │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘
```

You can also select a single webhook receiver, instead of fanning out.

## connect to prod

For instance, you can run a `tnl` publisher inside your VPC. Traffic between the `tnl` client and publisher uses end-to-end post-quantum encryption based on publicly trusted TLS certificates (from Let's Encrypt). The connection will attempt P2P hole-punched UDP and fall back to using relays (which can't read your encrypted traffic). Your db or Kubernetes API aren't publicly exposed:

```text
┌──[ private services ]──────────────┐
│                                    │
│       your laptop / CI / app       │
│                 |                  │
│       +---------+---------+        │
│       |                   |        │
│   direct UDP          tnl relay    │
│ when possible         fallback     │
│       |                   |        │
│       +---------+---------+        │
│                 |                  │
│    tnl publisher in your VPC       │
│                 |                  │
│       +---------+---------+        │
│       |                   |        │
│  PostgreSQL         Kubernetes API │
│                                    │
└────────────────────────────────────┘
```

For example, connect to a private PostgreSQL instance in Amazon RDS:

```bash
pnpm exec tnl connect orders
```

Team members use the printed connection settings with `psql` or their database driver and their normal database credentials. Kubernetes works with `kubectl` and your cluster's existing credentials.

### or from CI

The action uses GitHub's OIDC with secure, short-lived tokens to connect to the `orders` service. `tnl.connect("orders")` reads the local host, port, and TLS settings prepared by the action. The db password comes from GitHub secrets. See [GitHub Actions setup](https://github.com/tnldotdev/tnl#or-from-ci).

## questions

### does it deploy my software?

No. Your app stays on your laptop or server. tnl lets other people reach it.

### do visitors need to install tnl?

Not to open a preview in a browser. For private services, use the tnl client or SDK.

### who can connect?

People you allow. Use sign-in, share links, or tokens to control access.

### where does encryption end?

For web previews, on your device. For private services, at the publisher. Relays can't read the traffic.

### how is it different from tailscale or cloudflare tunnel?

Tailscale connects devices. tnl connects services, with worktree URLs and feedback built in. Unlike Cloudflare Tunnel, you can self-host it.

### can i use my own domain?

Yes. Run `tnl domain claim`, then add the DNS records it gives you.

### can i self-host?

Yes. You can run the whole stack yourself, for free.

### how much does it cost?

tnl.dev is free during private beta. Accounts and teams keep a free plan if paid plans arrive.
