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 want | Use | Extra setup |
|---|---|---|
| Laptop only; SSH is fine | The SSH tunnel you already have | None |
| Private access from your phone and laptops | Tailscale | Tailscale on the server and each device |
| Browser access on your own domain, with no app on each device | Cloudflare | A Cloudflare domain, cloudflared and an Access policy |
| You already run a VPN or HTTPS reverse proxy | Your own network | Point it at the loopback API |
Each option keeps the API on loopback. You never 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.
#Tailscale
A private https:// address that only your own devices can open. No domain needed.
- Install Tailscale on the server and on each device, signed in to the same tailnet. See Install Tailscale.
- Turn on MagicDNS and HTTPS certificates for your tailnet. You need Tailscale 1.52 or newer.
On the server, in the ccr-cloud folder:
SHELLnpm run setup -- --tailscale- 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):
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.
- Install
cloudflaredon the server and runcloudflared tunnel loginthere. See Cloudflare's locally managed tunnel prerequisites. - 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.
On the server, in the ccr-cloud folder:
SHELLnpm run setup -- --cloudflare ccr.example.comSetup 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.
- Run the tunnel start command that setup prints, on the server.
- 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 ccr-cloud. 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_HOSTinserver.envto 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. Pair it instead:
In the app on your computer, select Devices, then Pair a phone, and send the link to your phone, or on the server run:
SHELLnpm run pairwhich prints the link, and a QR code if
qrencodeis installed. SetCCR_CLOUD_PUBLIC_URLinserver.envto your HTTPS address so it prints a full link.- Open the link on the phone within 10 minutes. It works once.
The phone gets its own token and stays signed in. Devices lists paired devices; Revoke signs one out and stops its notifications. Disconnect on a paired phone revokes that phone. A paired device can do everything the access token can, so revoke devices you no longer use. The access token itself always keeps working.
#Install the app
On an HTTPS address (or localhost), install ccr-cloud 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 never stores task content for offline use.
#Next steps
- Notifications
- Configuration:
CCR_CLOUD_HOST,CCR_CLOUD_TUNNEL_NAMEand more.