Access from your phone

Your laptop's SSH tunnel isn't reachable from your phone. Once your first task works, choose one way to reach the server from other devices.

You wantUseExtra setup
Laptop only; SSH is fineThe SSH tunnel you already haveNone
Private access from your phone and laptopsTailscaleTailscale on the server and each device
Browser access on your own domain, with no app on each deviceCloudflareA Cloudflare domain, cloudflared and an Access policy
You already run a VPN or HTTPS reverse proxyYour own networkPoint it at the loopback API

Each option keeps the API on loopback. You don't need to open ports 8787 or 8788 to the internet. Connectivity can vary by network (for example, from mainland China), so test your choice on the network where you'll use it.

#Phone access through a relay (experimental)

The optional blind relay lets a home Mac make an outbound connection while the phone uses an encrypted channel pinned to the Mac's identity key. The relay sees routing metadata, frame sizes and timing, but no API content or owner token. Set CCR_CLOUD_RELAY_URL to a compatible relay's HTTPS origin and, for a self-hosted relay, CCR_CLOUD_RELAY_REGISTRATION_SECRET in the Mac's private server.env. The Mac's API stays on loopback. A directly authenticated caller can create a one-use payload with POST /api/relay/pairing. See phone access for scanning and pairing, the uuBright relay for accounts, configuration for settings, and the relay protocol for the channel design.

Disconnect on a relay-connected phone revokes that phone's device key on the Mac and removes its Push subscriptions before deleting the local key. If the Mac is offline, the phone still signs out locally and warns that it may remain trusted on the Mac; remove it under Devices when the Mac is online.

#Tailscale

A private https:// address that only your own devices can open. No domain needed.

  1. Install Tailscale on the server and on each device, signed in to the same tailnet. See Install Tailscale.
  2. Turn on MagicDNS and HTTPS certificates for your tailnet. You need Tailscale 1.52 or newer.
  3. On the server, from the installed server package:

    SHELL
    npm run setup -- --tailscale
  4. Open the printed https://HOST.TAILNET.ts.net/ address on a device in your tailnet and connect with the same owner token. Run a scratch task to check.

Setup uses Tailscale Serve and never enables Funnel, so the address isn't public. It won't replace another handler on that address. If Tailscale refuses the change, setup prints the permission fix to run, such as sudo tailscale set --operator=$USER.

To remove the address later (your tasks aren't affected):

SHELL
tailscale serve --https=443 off

#Cloudflare

Browser access on a hostname you control, such as ccr.example.com, without installing anything on each device. This path takes more setup.

Cloudflare terminates HTTPS, so it can see your traffic, including your owner token. Protect the whole hostname with a Cloudflare Access policy that allows only you.

  1. Install cloudflared on the server and run cloudflared tunnel login there. See Cloudflare's locally managed tunnel prerequisites.
  2. Create a self-hosted Access application for the hostname. Leave its path empty so it covers every path, and allow only your own email. Don't add bypass rules for specific paths.
  3. On the server, from the installed server package:

    SHELL
    npm run setup -- --cloudflare ccr.example.com

    Setup creates or reuses a named tunnel, adds the DNS record and writes the tunnel configuration. It then checks that the site and each API path ask for an Access login. DNS changes can take a few minutes to appear; rerun setup until it reports Cloudflare Access: a login is required.

  4. Run the tunnel start command that setup prints, on the server.
  5. On your other device, open the HTTPS address, sign in to Cloudflare Access, then enter your owner token.

There are two logins: Access protects the hostname, and the owner token authorizes uuBright Console. Setup refuses to overwrite existing DNS records or to reuse a tunnel whose credentials aren't on this server. Quick trycloudflare.com tunnels aren't supported. The API and the tunnel are separate processes, and both must be running.

#Your own VPN or reverse proxy

  • VPN: set CCR_CLOUD_HOST in server.env to the server's VPN address and limit access with your VPN's rules. Keep the runner endpoint on loopback.
  • HTTPS reverse proxy: proxy a dedicated HTTPS origin to 127.0.0.1:8787. Allow streaming responses and long read timeouts, because the app uses server-sent events.

Restart the service after editing server.env.

#Sign in on your phone

You don't need to type the access token on a phone. Connect it instead:

  1. Install the app on the phone first (see Install the app) and open it.
  2. On your computer, choose Connect your phone (the ⋯ menu, or Server settings → Devices). It shows an 8-character code and a QR code. On the server you can also run:

    SHELL
    npm run pair

    which prints the code and a link, and a QR code if qrencode is installed. Set CCR_CLOUD_PUBLIC_URL in server.env to your HTTPS address so it prints a full link.

  3. In the phone app, under Add a computer, type the code (or paste the link) and tap Add computer. Codes and links work once and expire after 10 minutes.

Browser and installed-app storage are separate on iPhone, so add the computer inside the app you intend to use. A QR code scanned with the Camera opens the browser, which asks whether to open the app instead or Use this browser instead. Pairing grants access to the server where that app is open; use your server’s HTTPS address for both devices. The app refuses a link created on a different server. Cloudflare Access sign-in, if configured, is still required separately.

Wrong codes are counted: five from one address in ten minutes are refused for the rest of that time, and ten across the server pause typed codes for ten minutes (links keep working). Behind a reverse proxy every phone shares the proxy's address, so the per-address limit applies to all of them together, unless you set CCR_CLOUD_TRUST_PROXY=1 (configuration) for a proxy that is the only way in.

The phone gets its own token and stays signed in. Devices lists paired phones; Revoke signs one out and stops its notifications. Disconnect on a paired phone revokes that phone, and pairing a phone again revokes its earlier pairing (if the server doesn't confirm, the app says so and retries each time it signs in). A paired device can do nearly everything the access token can (Who can do what), so revoke devices you no longer use. Adding and removing devices stays with you: only the access token can create a pairing code or revoke another device, so Connect your phone and Revoke work in the app on the computer (or in a browser signed in with the access token) and with npm run pair, and a paired device is refused. The Mac app's connection to a host it set up over SSH is the exception: it is paired owner-grade and can do both for that host. A paired device can still disconnect itself. The app shows it that way: on an ordinary paired device there is no Connect your phone, and Devices lists every device with a button only for the device itself, Sign out this device, next to a line saying who can add and remove devices. A device marked Owner-grade: can add and remove devices in that list is the Mac app's connection. Device names are shown without control and text-direction characters, so a name can't disguise itself or the text around it. The access token itself always keeps working.

#Install the app

On an HTTPS address (or localhost), install uuBright Console as an app from your browser's menu. On iPhone or iPad, use Share → Add to Home Screen, then open the installed app. You need to install it before notifications can work there.

The installed app opens offline, but viewing tasks and sending commands need a connection to your server. It doesn't store task content for offline use.

#Next steps