<!-- Source: https://console.uubright.com/docs/remote-access/ -->
# Access from your phone

Your laptop's SSH tunnel isn't reachable from your phone. Once your
[first task](https://console.uubright.com/docs/getting-started/) 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) | Tailscale on the server and each device |
| Browser access on your own domain, with no app on each device | [Cloudflare](#cloudflare) | A Cloudflare domain, `cloudflared` and an Access policy |
| You already run a VPN or HTTPS reverse proxy | [Your own network](#your-own-vpn-or-reverse-proxy) | Point 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](https://console.uubright.com/docs/phone-access/)
for scanning and pairing, [the uuBright relay](https://console.uubright.com/docs/relay-managed/) for accounts,
[configuration](https://console.uubright.com/docs/configuration/#phone-access-through-a-relay) for settings, and
the [relay protocol](https://console.uubright.com/docs/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](https://tailscale.com/docs/install).
2. Turn on MagicDNS and
   [HTTPS certificates](https://tailscale.com/docs/how-to/set-up-https-certificates)
   for your tailnet. You need Tailscale 1.52 or newer.
3. On the server, from the installed server package:

   ```sh
   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](https://tailscale.com/docs/reference/tailscale-cli/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):

```sh
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.

> [!WARNING]
> 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](https://developers.cloudflare.com/tunnel/features/locally-managed-tunnels/create-local-tunnel/).
2. Create a
   [self-hosted Access application](https://developers.cloudflare.com/cloudflare-one/setup/secure-private-apps/private-web-app/)
   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:

   ```sh
   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](https://console.uubright.com/docs/operations/#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](#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:

   ```sh
   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](https://console.uubright.com/docs/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](https://console.uubright.com/docs/security/#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

- [Notifications](https://console.uubright.com/docs/notifications/)
- [Configuration](https://console.uubright.com/docs/configuration/): `CCR_CLOUD_HOST`, `CCR_CLOUD_TUNNEL_NAME` and
  more.
