<!-- Source: https://console.uubright.com/docs/beta/ -->
# Developer beta: Mac and phone

Install the public **uuBright Console** beta to run Claude Code or Codex on **your Mac**. Hosted phone relay access requires a separate invitation. Adding a Linux host over SSH is [experimental and optional](#experimental-optional-add-a-remote-host-ssh).

## Before you start

- macOS **13 Ventura or newer**, on Apple silicon or Intel.
- Claude Code **or** Codex CLI installed, signed in and able to answer a prompt in
  Terminal. Either one is enough. Codex CLI 0.163.0 or newer is supported.
- Git and GitHub CLI (`gh`). Sign in with `gh auth login` if you want tasks to push
  a branch and open a pull request. Set `git config --global user.name` and
  `user.email` for commits.
- A Git repository with an initial commit. Pick one you trust: on This Mac, tasks
  run as your macOS account and can read files that account can read.
- The **signed and notarized DMG** from the [Mac beta download page](https://console.uubright.com/beta/download/). Phone access is configured separately.
  macOS should open the app without asking you to choose **Open Anyway**.

## Install and run a first task on This Mac

1. Open the DMG, drag **uuBright Console** into **Applications**, eject the disk image, and
   open the app from Applications.
2. Choose **This Mac**. The app starts a private local service and signs you in.
   No server address or token is needed. The first launch can take a while; keep
   the window open. If it doesn't finish, use **View logs** or **Retry**.
3. Open **⋯ → Server settings → Setup check**. It looks for recent repositories,
   Git identities, push access, `gh` accounts and Claude Code Router. Add your
   repository, choose the right Git identity, and sign in to GitHub if it asks.
   You don't need Claude Code Router to use your Claude Code or Codex login. After
   fixing something, choose **Check again**.
4. Tasks use the Claude Code or Codex login already on this Mac; there's nothing
   to choose. **Connect your model** is only for using an Anthropic API key, AWS
   Bedrock or Claude Code Router instead (see
   [Bring your own model](https://console.uubright.com/docs/bring-your-own-model/)). A small first task is the way to
   confirm model access.
5. In a coding workspace, choose **Start your Manager**, pick your repository as the
   project, and describe a small change it can check. Answer its questions and
   approvals under **Needs you**. Review its branch, tests and pull request before
   you merge. See [Your Manager and its workers](https://console.uubright.com/docs/manager/).

The Manager hands longer work to Workers, on Claude Code or Codex, whichever you
have installed; by default they use the Manager's own agent. When a Worker reports
a pull request ready, the Manager asks an independent reviewer to check it. The
reviewer runs on the other agent when you have both, otherwise in a fresh read-only
session of the same one, and gives a PASS or FAIL on the PR's latest commit. The PR
stays held until it has a PASS; its card shows **Reviewer PASS** or **Reviewer
FAIL**. You decide on merging, and **Skip review** lets a PR through without one.

To see how the week went, choose **Insights** in the sidebar: tasks finished, time
your agents ran and waited on you, and spend. It's on the Mac, not on a paired
phone.

## Connect your phone

These steps are for testers with a hosted relay invitation.

1. In the **uuBright Console** menu, choose **Phone access settings…**, then **Use uuBright
   relay**. Sign in with the uuBright username and password from your invitation.
2. On the Mac, choose **Access from phone…** in the **uuBright Console** menu, or open
   **⋯ → Server settings → Devices**. Choose **Connect your phone**. It shows a QR
   code and a short code. The code works once, for 10 minutes; choose **New code**
   for another.
3. On the phone, scan the QR code with the camera. To use the Home Screen app,
   tap **Share → Add to Home Screen** and open **uuBright Console** from your Home Screen.
4. In the Home Screen app, tap **Add a computer** and type the short code from
   the Mac. The phone finds the computer as soon as the eighth character is in.
5. Check that the phone and the Mac show the same fingerprint, then tap **It
   matches. Add computer**. The phone connects straight away.

Your phone keeps Safari and the Home Screen app apart. A computer you add in a
Safari tab stays in that tab. To use the Home Screen app, add the computer there,
by its short code. To stay in Safari instead, check the fingerprint on the page the
QR code opens and tap **It matches. Add computer** there.
See [Access through an encrypted relay](https://console.uubright.com/docs/phone-access/) to reconnect or remove a
phone.

## Problems and feedback

On the Mac or the phone, open the affected task and choose **⋯ → Report a
problem…**. Describe the steps and what you expected, choose **Build report**,
read the preview, then **Download report** and email the file to
[support@uubright.com](mailto:support@uubright.com). The app doesn't send it
on its own. If no task opens, the same menu on the main page makes a report for the
whole server. See [what's in the report](https://console.uubright.com/docs/troubleshooting/#report-a-problem).
Try a report from each device early in the beta, so you know it works when you
need it.

For ideas or rough edges, choose **⋯ → Send feedback** or **Share your week**, or
email the same address. Include the app version, what you tried and what you
expected. Leave out tokens and private code unless you choose to share them.

## Current limits

- Tasks on This Mac run as your macOS account. Use trusted repositories. Docker
  isolation and a separate user per task aren't part of this beta.
- The phone shows tasks, messages and approvals (**Needs you**). Live screen and
  browser control aren't finished. A sleeping or offline computer can't answer the
  phone.
- uuBright Console keeps the Mac awake while tasks run (**Keep Mac awake while tasks run** in
  the **uuBright Console** menu), but not while a task waits for your approval. If you'll
  answer from your phone, keep the Mac awake and online while approvals are pending.
- A published file may fail to open on the phone. Open it on the Mac, and report
  it.
- Codex uses your existing Codex login. A proxy or model
  account problem can stop a first task.
- The SSH host flow is experimental; see its [known limits](#known-limits).

## Update or remove

To update, open **uuBright Console → Check for Updates…** and follow the prompts.
The app checks the beta feed periodically. If you need to install manually, get
the current signed and notarized DMG from the beta download page, quit uuBright
Console, and replace it in Applications. Reopen it to update the local service
while keeping your tasks. If the Mac logged out or restarted during a task, open the
task and choose **Resume**. If the app asks to **Reconnect This Mac…** after an
update, confirm it: your tasks, pairings and settings stay in place.

To uninstall, choose **Quit and stop tasks** in the **uuBright Console** menu, then move the
app to the Trash. Your tasks and settings stay in
`~/Library/Application Support/CCR Cloud/`; the login item is
`~/Library/LaunchAgents/cloud.ccr.desktop.local.plist`. Remove the data folder only
after you've saved anything you want to keep. If you no longer want phone access,
revoke the phone under **Server settings → Devices** and sign out of the uuBright
relay before you remove the app.

## Experimental (optional): Add a remote host (SSH)

You don't need this for the beta. Try it only if your code lives on a Linux machine
you reach over SSH and you're comfortable fixing things on that host.

If your code lives on a Linux machine you reach over SSH, the app can install the
server there and add that computer next to This Mac. You don't run any commands on
the host. Set up This Mac first: the remote host is added to it.

### What the host needs

- Linux on x64 or arm64, with at least 2 GiB of free disk.
- Node.js **22.18 or newer**, Git and tmux on the login `PATH`.
- SSH with a **key or the SSH agent**. Password and two-factor sign-in don't work
  in this beta. Check that `ssh user@host` works in Terminal without a password
  prompt, or pick the key file in the app (below).
- To run tasks there: Claude Code or Codex installed and signed in, for the user you
  connect as. You can install the server first and set up the agent later.
- OpenSSH 6.7 or newer on the host, with Unix-socket forwarding allowed
  (`AllowStreamLocalForwarding`, on by default). If it's off, adding the host says so.
- To come back on its own after a reboot: `systemd --user` with lingering for your
  user. See [After a reboot](#after-a-reboot).

The host needs no source checkout and no GitHub access to install the server.

### Install and connect

1. In the **uuBright Console** menu, choose **Add a remote host…**. You can also choose
   **Your computers…** in the sidebar, then **Add a remote host…**.
2. Pick a host under **SSH config hosts**, which lists the hosts in your SSH config,
   including `Include`d files. Or type one under **Or enter a host**, such as
   `user@example.com:22`.
3. If SSH config or your agent doesn't already provide the key, choose **Choose key
   file…** under **SSH private key (optional)**. The key stays on this Mac; an
   encrypted key must be unlocked in your SSH agent. A key whose path contains `%`
   isn't accepted; rename or move it first. **Use default keys** goes back to SSH
   config or the agent.
4. Choose **Connect and check host**.
5. The first time, the app shows **Trust this SSH host key?** with the host's
   fingerprint. Compare it with the fingerprint you expect, then choose **Trust host
   key**. The app never signs in before you approve the key. If a host's key
   changes later, the app refuses to connect.
6. The app shows a checklist. Each required item is marked **✓** or **Needs
   attention:** with a fix. Fix what it asks on the host, then choose **Connect and
   check host** again. Claude Code and Codex are marked **Set up later:** if they're
   missing; they don't block the install. When it says the host is ready, continue.
7. Choose **Install and connect**. The app uploads the server, checks it, starts it
   and pairs it. When it's done, it shows **Remote computer added alongside This
   Mac.** If no agent is set up yet, it reminds you to install Claude Code or Codex
   and connect model access before running tasks.

The host now appears in your computers next to This Mac. Start tasks on it from
**New task**. Its tasks keep running when your Mac sleeps or disconnects.

Because the app set the host up over your SSH sign-in, its pairing with the host is
**owner-grade**: from the Mac you can **Connect your phone** to the host and revoke
the host's devices, which an ordinary paired device can't. A phone you connect this
way is an ordinary device. A host added before this was available is paired as an
ordinary device and those two actions are refused; remove the host from **Your
computers…** and add it again to get the owner-grade pairing.

### What's installed where

On the host, in the home folder of the user you connect as:

- `~/.uubright/current` points to the installed server version.
- `~/.local/share/ccr-cloud` holds the server's data: tasks, settings and logs.

The server runs in a tmux session, so it keeps running after SSH disconnects. The Mac
reaches it through an SSH tunnel to the server's private control socket in that data
folder, not a network port. The app opens and manages the tunnel, so you don't open
or forward a port yourself.

Where the host allows it, setup also installs a boot unit,
`~/.config/systemd/user/ccr-cloud.service`. See [After a reboot](#after-a-reboot).

### Reconnect

When you reopen uuBright Console, it reopens the tunnel to each host on its own. **Add a
remote host…** lists them under **Managed hosts** as **Connected**,
**Reconnecting…** or **Offline**. Choose **Refresh status** to check again.

If the app reaches a host but not its server, it starts the server again over SSH
and shows **Restarting service on <host>…**. If that fails, it shows **The service on
<host> is unavailable (…). Retrying…** and tries again, waiting longer each time, up
to five minutes. Restarting keeps the server's data and owner token, and the app
connects again only if the host still runs the same server.

If the host now runs a different server, for example because its data folder was
replaced, the app says so and doesn't reconnect. To use it, add it again with **Add a
remote host…**.

### After a reboot

A reboot stops the server and the tasks running on it. The server comes back in one
of two ways:

- **Boot unit.** If the host has `systemd --user` and lingering is on for your user,
  setup installs `~/.config/systemd/user/ccr-cloud.service`, which starts the server
  at boot. Setup turns lingering on itself when the host allows that without a
  password; it doesn't use sudo. Otherwise ask an administrator to run
  `sudo loginctl enable-linger <your user>`, then run **Install and connect** again.
- **The Mac.** Without the unit, the server starts again when uuBright Console on your Mac
  next reaches the host, as described in [Reconnect](#reconnect). Until then the
  host shows as unavailable.

Tasks that were in the middle of a turn start again on their own, a few at a time,
and continue the turn. Idle tasks stay stopped until you send them a message or
choose **Resume session**.

### Known limits

- Only SSH key or agent sign-in works. Password and two-factor prompts don't.
- The app doesn't install Claude Code or Codex on the host.
- Without a boot unit, a rebooted host stays unavailable until uuBright Console on your Mac
  reaches it again.
- A host added with an earlier beta may show **Added by an older version. Add it
  again to connect it securely.** If it doesn't connect on its own, add it again with
  **Add a remote host…**.
- The app doesn't update or uninstall the server on the host yet.
- The phone reaches This Mac. A remote host added over SSH isn't set up for phone
  access in this beta.

### Remove it from the host

Turn off the boot unit if setup installed one
(`systemctl --user disable ccr-cloud.service`, then delete
`~/.config/systemd/user/ccr-cloud.service`). Stop the server with
`tmux kill-session -t ccr-cloud`, then remove `~/.uubright` and, if you don't need its
tasks, `~/.local/share/ccr-cloud`.
