useburrow — the Burrow CLI

Secure, EU-hosted tunnels for local development. Point a public HTTPS URL at your localhost over an outbound wss connection (so it traverses any firewall or NAT), inspect every request in a local web UI, and let AI agents open and inspect tunnels through a first-class MCP server.

useburrow.dev · DSGVO-first · Node-native

npx useburrow http 3000

  ◐ Burrow tunnel ready
    https://cool-otter-42.useburrow.dev  →  http://127.0.0.1:3000
    Inspector  http://127.0.0.1:4040

Package name vs. command name: the npm package is useburrow, the command it installs is burrow (with a bw alias). So npx useburrow http 3000 and—after a global install— burrow http 3000 do the same thing.

Install

# Zero-install, always latest:
npx useburrow http 3000

# Or install globally and use the `burrow` command:
npm i -g useburrow
burrow http 3000
bw http 3000          # short alias

Requires Node ≥ 22 (the undici HTTP engine requires Node 22.19+; Node 20 is end-of-life).

Commands

| Command | What it does | |---------|--------------| | burrow init | Interactive setup wizard: login, pick a target, scaffold burrow.yml, and launch. Also runs when you type burrow with no command. | | burrow http <port\|url> | Tunnel an HTTP(S) service on a local port (or full URL). | | burrow share <port\|url> | Alias for http with sharing-friendly defaults. | | burrow tcp <port\|host:port> | Tunnel a raw TCP service (e.g. Postgres). | | burrow start | Start every service defined in a burrow.yml multi-service config. | | burrow login / logout / whoami | Device-code auth; show / clear the stored account. | | burrow tunnels | List active tunnels for your team. | | burrow companion | Run an idle daemon so AI agents can open tunnels on demand. | | burrow mcp | Print MCP server connection details for AI agents. | | burrow config <get\|set> <key> [value] | Read/write ~/.burrow/config.toml. | | burrow doctor | Connectivity diagnostics (DNS, egress, proxy, ports). | | burrow update | Show the current version and how to update. |

burrow http options

| Option | Default | Description | |--------|---------|-------------| | --target <url> | — | Forward target (alternative to the positional port/URL). | | --subdomain <name> | — | Request a reserved subdomain (requires login + entitlement). | | --domain <host> | — | Use a verified custom domain. | | --region <region> | eu | Edge region. | | --basic-auth <user:pass> | — | Protect the tunnel at the edge. | | --host-header <mode> | rewrite | Forwarded Host: handling: rewrite, preserve, or a literal value. | | --header <kv> | — | Inject a "Key: Value" header on every forwarded request (repeatable). | | --inspect <port> | 4040 | Local inspector port. | | --no-inspect | — | Disable the local inspector. | | --qr | — | Print a scannable QR code of the public URL (handy for mobile testing). | | --json | — | Machine-readable output (CI-friendly). | | --ws-url <url> | — | Override the edge WebSocket URL (advanced). | | --allow-link-local | — | Allow link-local / cloud-metadata targets (SSRF guard override). |

Local inspector

By default burrow http serves a local request inspector at http://127.0.0.1:4040 — a React SPA that shows the live request list, full request/response detail, replay, filtering, and a webhook helper. Request bodies are local-only by default and never leave your machine unless cloud history is explicitly enabled for your team.

Disable it with --no-inspect, or move it with --inspect <port>.

Multi-service: burrow.yml

# burrow.yml — start them all with `burrow start`
services:
  - name: web
    http: 3000
    subdomain: acme
  - name: api
    http: 8080
  - name: db
    tcp: 5432

burrow start            # reads ./burrow.yml
burrow start --config infra/burrow.yml

Programmatic SDK

import { tunnel } from 'useburrow'

const t = await tunnel({ http: 3000, subdomain: 'acme' })
console.log(t.url)      // https://acme.useburrow.dev
await t.close()

Framework integrations

// Vite — vite.config.ts
import { burrow } from 'useburrow/vite'
export default { plugins: [burrow({ subdomain: 'acme' })] }

// Next.js
import { withBurrow } from 'useburrow/next'
export default withBurrow({ /* next config */ })

// Nuxt — nuxt.config.ts
export default { modules: [['useburrow/nuxt', { subdomain: 'acme' }]] }

See integrations/README.md for the full integration docs.

MCP server (for AI agents)

Burrow ships a first-class MCP server so agents can open and inspect tunnels:

burrow mcp              # prints the endpoint + how to mint a scoped token

Point your agent at the printed Streamable-HTTP endpoint with a Bearer MCP token (minted in the dashboard). Run burrow companion to keep an idle client registered so an agent can open a tunnel on demand.

Authentication

burrow login            # device-code flow; stores the token in ~/.burrow/config.toml
burrow whoami
burrow logout

BURROW_TOKEN (a brw_pat_… personal access token) is honored as an alternative to an interactive login — handy in CI:

BURROW_TOKEN=brw_pat_xxx npx useburrow http 3000 --subdomain acme

Environment variables

| Variable | Purpose | |----------|---------| | BURROW_TOKEN | Auth token (overrides the stored login). | | BURROW_API_URL | Override the API base (default https://app.useburrow.dev). | | BURROW_MCP_URL | Override the MCP endpoint (default https://mcp.useburrow.dev). | | BURROW_HOME | Override the config dir (default ~/.burrow). |

Development

pnpm install
pnpm build              # builds the inspector SPA, then the CLI + SDK bundles (tsup)
pnpm test               # vitest
pnpm typecheck

The published tarball ships dist/ plus the prebuilt inspector SPA (inspector-web/dist); the prepack hook rebuilds both before npm pack / npm publish.

License

MIT © Pixel & Process UG (haftungsbeschränkt)