Guides
Import an existing setup
Move the routes of a cloudflared config.yml (a locally-managed tunnel) onto Teitunnel: where it looks, what can be imported, the plan you review, what happens to the old tunnel and its DNS records, and how to switch back.
If you already run cloudflared with a config.yml (a locally-managed tunnel, set up with
cloudflared tunnel create and cloudflared tunnel route dns), Teitunnel can bring its
routes over, so you manage them in one place with previews, checks and the Doctor. The
import is a normal reviewed change, and your files and the old
tunnel are left as they are, so you can switch back.
What Teitunnel looks at
Teitunnel only reads; it never changes these files. It looks where cloudflared itself does:
~/.cloudflared,~/.cloudflare-warpand~/cloudflare-warp;/etc/cloudflared,/usr/local/etc/cloudflaredand Homebrew's/opt/homebrew/etc/cloudflared(macOS and Linux);%SystemRoot%\System32\config\systemprofile\.cloudflared, where the cloudflared Windows service keeps its files;- the
--configfile of every cloudflared process running on this computer that Teitunnel didn't start.
It reads config.yml, config.yaml and any other .yml/.yaml file there that has routes
(per-tunnel files), each once, and none over 1 MB. From a credentials file
(<tunnel-id>.json) it reads only the account and tunnel ids, never the secret.
In the app
Open the import
In Routes, choose Import from cloudflared in the toolbar. The button appears when Teitunnel found at least one route it knows how to import.
Pick the routes
The sheet lists each config file with its routes, as hostname path → service. Every route that can be imported starts ticked; untick the ones to leave behind. Routes that can't be imported are shown greyed out, with the reason (see below).
Review
Choose Review. Teitunnel plans one change, Import 3 routes from cloudflared: the routes go onto this computer's tunnel (created first if you don't have one yet), and each hostname's DNS record is pointed at it.
The records point at the old tunnel, and Teitunnel didn't create them, so the plan shows each one (… already has a DNS record (CNAME 6a1f….cfargotunnel.com) that Teitunnel didn't create. It will be replaced.) and asks you to tick Replace the existing records.
Apply and check
Choose Apply. Each hostname is checked through Cloudflare's edge, like a new route. If a step fails, everything is undone and the old setup keeps serving.
The import is recorded in Activity under Imports.
Check each imported route's settings after importing: select it, choose Edit route, and
look under Advanced ▸ Origin settings. An HTTPS service with a self-signed certificate,
for example, needs Accept self-signed certificates (noTLSVerify in config.yml).
What happens to the old setup
- Your files (
config.yml, the credentials file) are untouched. - The old tunnel stays in your Cloudflare account, and its cloudflared keeps running. Since the DNS records now point at Teitunnel's tunnel, visitors reach this computer's connector instead.
- cloudflared still running? It shows under Tunnels ▸ Also on this Mac (this PC on
Windows, this computer on Linux), and the Doctor mentions it: cloudflared is running
tunnel … outside Teitunnel. Once you're happy, choose Stop… there. If it runs as a
background service (It runs as a background service, which may start it again), also
disable the service, for example
sudo cloudflared service uninstall. - Switching back: remove the routes in Teitunnel (their DNS records are now Teitunnel's,
so they're removed too), then run
cloudflared tunnel route dns <tunnel> <hostname>for each hostname and start the old cloudflared again. - Cleaning up for good: when you no longer need the old tunnel, delete it with
cloudflared tunnel delete <tunnel>or in the Cloudflare dashboard.
What can't be imported
Each route that can't be imported says why:
| Reason shown | What to do |
|---|---|
| Not in this account's domains | The hostname belongs to another Cloudflare account. Switch accounts in the toolbar and import from there. |
| Already routed | A route with this hostname and path exists in Teitunnel. |
| Wildcards are only supported as the first label | Only *.yourhost.com-style wildcards work. Add the route by hand with another name. |
| “…” isn't a service Teitunnel routes to | The service isn't one of the kinds a route can point at. Add the route by hand. |
| It has settings Teitunnel can't carry over yet: access, bastionMode | The rule has originRequest settings Teitunnel doesn't manage. Add the route by hand, then set those in the Cloudflare dashboard if you still need them. |
Two notes can also appear for a whole file:
- This file has settings for all routes (originRequest). They aren't imported; check that the routes work after importing.
- Couldn't read it: … or It isn't valid YAML: … when the file can't be read.
Catch-all rules (the last - service: http_status:404) aren't routes and are skipped:
Teitunnel always keeps its own catch-all last.
From a terminal
There's no import command. To move a route by hand, add it with the same settings and confirm the record replacement:
teitunnel route add app.yourhost.com https://localhost:8443 --no-tls-verify --replaceThe CLI reference lists every origin setting as a flag. For a whole setup kept in a repository, a project file is usually the better home.
Troubleshooting
- No Import button. Teitunnel found no importable route: check that the config file is
in one of the folders above (or that its cloudflared is running) and has
hostname:rules. - Every route says Not in this account's domains. Pick the account that holds the domain in the toolbar.
- "Something changed in Cloudflare since you reviewed this change." A record changed while you were reviewing. Choose Review Again.
Related
- What is Cloudflare Tunnel?
- Export your setup: the other direction.
- DNS ownership
- Several tunnels: run an existing remotely-managed tunnel here with Run on This Mac….
Last updated on
Accounts and permissions
Connect Cloudflare accounts with Sign in with Cloudflare or an API token, what each permission is for, how to fix a missing one in place, and where credentials are kept.
Export your setup
Turn this computer's Cloudflare Tunnel and routes into a cloudflared config.yml, a Docker Compose service or Terraform with import blocks, from the app or with teitunnel export. What each file contains, how to use it, and why no secret is ever included.