Getting started

Cloudflare setup

How to set up burrow with Cloudflare for persistent named tunnel URLs.

What you need

A Cloudflare account - free at dash.cloudflare.com/sign-up
A domain on Cloudflare - ~$10/yr. You can use any registrar; only the DNS needs to be managed by Cloudflare (free nameserver change).
burrow installed - see the install section on the main page.
Only need a quick public URL with no account? Skip this guide and run burrow share 3000. It works immediately with no setup.
1

Add your domain to Cloudflare

If you already have a domain, you only need to point its nameservers to Cloudflare. Cloudflare's DNS is free and you keep your existing registrar.

Go to dash.cloudflare.com, click Add a site, enter your domain, and choose the free plan. Cloudflare will scan your existing DNS records and give you two nameservers to set at your registrar. DNS propagation takes up to 24 hours.

If you don't have a domain yet, register one anywhere (Cloudflare Registrar, Namecheap, etc.) and then follow the steps above.

2

Find your Account ID

Go to dash.cloudflare.com. At the top right of the dashboard, click the ⋮ icon next to the + Add button and select Copy account ID. You'll enter this when running burrow init.

3

Create an API token

Go to dash.cloudflare.com/profile/api-tokens and click Create Token, then Create Custom Token. Do not use a template - burrow needs permissions that no template covers.

Exact permissions required. Add all three rows below under Permissions. Getting this wrong will cause burrow up to fail with an API error.
Resource type Resource Permission Why
Account Cloudflare Tunnel Edit Creates and manages the tunnel object
Zone DNS Edit Creates CNAME records pointing your domain to the tunnel
Zone Zone Read Looks up your zone ID from the domain name

Under Zone Resources, set Include - Specific zone and select your domain. Under Account Resources, select your account. Click through to create the token and copy it - you can only see it once.

4

Run burrow init

Run burrow init and enter the API token and Account ID from the previous steps. burrow will validate your credentials and install cloudflared automatically.

$ burrow init Setting up Burrow with Cloudflare Tunnel. Cloudflare API Token: •••••••••••••••••••••• Cloudflare Account ID: abc123def456 Validating credentials... ok. Installing cloudflared... ok. Burrow is ready.
Each team member runs this once. Credentials are stored locally in ~/.burrow/auth.json and never go in the repo. The .burrow.yaml config file you create next is what gets committed.
5

Create .burrow.yaml

Create a .burrow.yaml file at the root of your project. Define each service you want to expose with a name, local port, and domain.

provider: cloudflare tunnels: - name: api port: 8080 domain: api.yourapp.com - name: frontend port: 3000 domain: frontend.yourapp.com

Commit this file to your repo. Teammates who have run burrow init can immediately run burrow up with no additional setup.

Omit the domain to get a free temporary URL. Tunnels without a domain field use trycloudflare.com and don't require a Cloudflare account. You can mix both in the same file.
6

Start your tunnels

Make sure your local services are running on the ports defined in .burrow.yaml, then run:

$ burrow up Starting tunnels... [up] api -> https://api.yourapp.com [up] frontend -> https://frontend.yourapp.com All tunnels running. Press Ctrl+C to stop.

DNS records are created automatically on first run. The same URLs will work every time you restart, for every teammate.

Need help? Open an issue on GitHub. For managing tunnels once they're running, see the commands reference.