Reaching the relay through a Cloudflare Tunnel

A Cloudflare Tunnel gives your relay a public HTTPS address without a server of your own and without opening a port on your router. OAR can run Cloudflare's cloudflared program for you: it starts it with the relay, restarts it when it drops and shows its state in the status dot. Choose it when you have a domain on Cloudflare and want to reach the relay from a phone or another network, or when you need HTTPS for installing the page as an app and push notifications.

cloudflared connects outward to Cloudflare. The relay keeps listening on this machine only (localhostOnly stays true), and Cloudflare carries requests for your hostname down that connection to the relay's port.

What you need #

• A Cloudflare account with Zero Trust, and a domain (a zone) on it for the public hostname.
• cloudflared installed on the machine that runs the relay. OAR does not include it and does not install it.
• A tunnel that you create in Cloudflare. OAR runs it from the tunnel's token.

The relay runs the program named in cloudflaredTunnel.binary, or else the cloudflared it finds on its PATH. Install it with:

On Windows, a .cmd or .bat launcher does not work. OAR starts a .exe or .com file.

Setting it up #

1. In your Cloudflare Zero Trust account, create a tunnel. Copy its token.
2. Give the tunnel a public hostname on your zone, for example relay.example.com, and point it at http://localhost:3333. If you changed port in config.json, use that port. This routing lives in Cloudflare, not on your machine.
3. Add the cloudflaredTunnel block to config.json with the token (see Config keys).
4. Restart the relay with oar restart.

Open https://relay.example.com/ in a browser. You sign in with the access token as usual.

The config block #

{
  "cloudflaredTunnel": {
    "mode": "managed",
    "required": false,
    "token": "<tunnel token>",
    "binary": "cloudflared",
    "extraArgs": []
  }
}

The old form "enabled": true still works for mode: "managed". Three environment variables override the file: COPILOT_CLOUDFLARED_MODE, COPILOT_CLOUDFLARED_TOKEN and COPILOT_CLOUDFLARED_BINARY. The config.json reference lists the keys with the other tunnel settings, and the environment variables page lists the variables.

The relay hands the token to cloudflared as a command-line argument (cloudflared tunnel run --token <token>), not through the environment. On a machine with other users, the token can therefore show up in the list of running processes. The relay's log shows it as <redacted>.

How it behaves #

• Start and stop. The relay starts cloudflared when it starts and stops it (a termination signal) when it shuts down.
• Connected. The tunnel counts as connected when cloudflared reports a registered connection, or, failing that, when it has run for five seconds.
• Drops. When cloudflared exits, the relay starts it again after a wait of about 5, 10, 20, 40 and then 60 seconds, each with up to 20 percent added. The steps start over after a connection that lasted more than 30 seconds.
• Bad token or deleted tunnel. If cloudflared exits within 10 seconds three times in a row, the relay reports the error auth-or-config and from then on retries only about once a minute.
• No cloudflared. The relay starts as usual and the tunnel stays off. It looks again every minute and starts the tunnel once the program is there. If you installed it into a folder that is not on the relay's PATH, restart the relay.

Required tunnel #

With required: true the relay does not take messages from the queue while the tunnel is not connected. That includes the time before it first connects and a missing cloudflared or token. Use it when the relay is only useful if you can reach it from outside. Messages wait in the queue and run once the tunnel is connected (see turns and the queue).

Seeing the state #

The relay does not know your public hostname, because the routing lives in Cloudflare, so none of these shows it.

Telling tunnel traffic apart #

Cloudflare adds a cf-ray header to every request it forwards. The relay uses it to tell a request that came through the tunnel from one made on this machine. To also treat the headers your own edge adds this way, list them in tunnelMarkerHeaders. publicHostnames lists the hostnames that reach the relay, and trustProxy says which proxies the relay believes about the forwarded address. The default, "loopback", suits cloudflared on the same machine. All three are in the config.json reference.

A second hostname for previews #

Previews need their own hostname, so a previewed app never shares a login cookie with the relay. Add it to the same tunnel as a second public hostname that points at the preview listener (http://127.0.0.1:3334 by default). The previews page has the ingress example and the previews block. Put the relay's hostname into publicHostnames.

Cloudflare Access in front of the relay #

A Cloudflare Access application over the relay's hostname applies to every visitor, including viewers of a shared conversation. Without an exception they are asked to sign in and the link does not work. Let /shared/* and /api/shared/* through without a login.

Do not add a Cloudflare cache rule for /api/shared/*. A shared page reloads that address to follow the conversation, and a cached answer would keep showing an old state. The relay marks every API answer with Cache-Control: no-store, and every answer with CDN-Cache-Control and Cloudflare-CDN-Cache-Control set to no-store. Cloudflare obeys those two ahead of a cache rule in your zone.

Security #

A tunnel puts the relay on the public internet. The access token is what keeps others out. See The access token and who can reach the relay and What OAR exposes.

The relay's session workers connect over sockets that only run on this machine. Because a public tunnel forwards every path, the relay answers 403 to a request on those paths that carries cf-ray or one of your tunnelMarkerHeaders, and the log notes it with [tunnel-guard]. Shared links, which arrive over the tunnel without a login, are not affected.

Troubleshooting #