<!-- Source: https://console.uubright.com/docs/operations/ -->
# Operate your server

Keep uuBright Console running: restart it, update it, back it up and watch host
resources. Run server commands as the service user from the installed server
package.

## Managed existing-host phase-1 flow

For a customer-owned SSH host, start with [Getting started](https://console.uubright.com/docs/getting-started/):
check Node.js, Git, tmux and the agent; install under a dedicated user; connect
through SSH; run a scratch task and a first reviewed change. A second compatible
host is needed for a recovery drill. The proposed management service would add
runtime updates, health alerts, scheduled encrypted off-host backups and guided
restore. Its eight-hour work window would stop new managed execution at expiry,
then settle and report a final checkpoint; it would not shut down the customer's
server. This is planning scope, not a feature enabled by the current install.
Model and host bills remain with the customer, and local execution continues
without the management service.

## Where things run

Setup starts the control plane in a tmux session named `ccr-cloud`. Each task's
runner runs in its own tmux session on hosts with tmux. [Desktop local mode](https://console.uubright.com/docs/local-mode/)
can run task runners in detached process groups instead, so tasks keep running while you restart or
update the control plane.

```sh
tmux attach -t =ccr-cloud      # view the control plane console; detach with Ctrl-b, then d
```

## Restart the service

Restart after editing `server.env` or updating the code. Stopping the control plane
doesn't stop tasks; their runners reconnect when it comes back.

```sh
tmux kill-session -t =ccr-cloud
npm run setup -- --start
npm run doctor -- --service
```

`npm run setup -- --start` never restarts a service that's already running, so stop
it first.

## Update uuBright Console

On Mac, choose **Check for Updates…** from the app menu. The app verifies
a downloaded update and asks you to restart to install it. If a task is
running or waiting for you, you can defer the restart.

For a Linux host installed through the Mac app, open **Add a remote host…**
and find **Update host** under **Managed hosts**. Let the host finish its work
and answer any pending approvals first. For other installations, follow the
update instructions provided with the newer server package.

Refresh the browser afterwards. See [Troubleshooting](https://console.uubright.com/docs/troubleshooting/#the-app-and-server-dont-match)
if the app and server report different versions.

## After a reboot

A reboot stops tmux, so it stops the control plane and every task.

On Linux with `systemd --user`, `npm run setup -- --start` also installs a user unit,
`~/.config/systemd/user/ccr-cloud.service`, that starts the `ccr-cloud` tmux session at
boot. A user unit runs at boot only when lingering is on for your user. Setup turns it on
with `loginctl enable-linger` when your system allows that without a password, and never
uses sudo. If setup prints `NOTE Not started at boot`, either ask an administrator to run
`sudo loginctl enable-linger <your user>` and run setup again, or start the service by hand
after each reboot. `CCR_CLOUD_BOOT_START=off npm run setup -- --start` skips the unit. To
remove it: `systemctl --user disable ccr-cloud.service` and delete the file.

The unit only starts the tmux session when it is missing; it never stops or restarts a
running service, so the commands above still manage it. Its logs are the same tmux pane.

Without the unit, after the server starts:

1. Run `npm run setup -- --start`.
2. Start Tailscale Serve or your Cloudflare tunnel again if you use one; the unit doesn't.

A host the desktop app installed over SSH needs neither step: when the app can't reach the
service it runs the same `setup --start` over SSH, and connects again only if the server
still has the same identity and port.

Setup, `managed-pair` and the app talk to the service only over its Unix socket in the
private data folder ([control socket](https://console.uubright.com/docs/api/#control-socket)), never the TCP port. Another
user's program that took the port after a reboot gets nothing, even if it repeats this
server's public instance id, and setup reports the port as in use (`EADDRINUSE`).

Tasks that were in the middle of a turn start again on their own, a few at a time, and
[continue the turn](https://console.uubright.com/docs/reliability/#turns-cut-off-by-a-crash-or-restart). Idle tasks
stay stopped until you send them a message or select **Resume session**.

## Back up your data

Back up the data directory, `~/.local/share/ccr-cloud` by default, or wherever
`CCR_CLOUD_DATA` points. It holds the owner token, task records and logs, task
workspaces with uncommitted edits, saved projects, push keys and registered
devices.

Keep it private: it contains credentials and task content. Task branches alone
don't preserve uncommitted work. Never delete the data directory to fix a login
problem.

## Logs

| What | Where |
|---|---|
| Control plane | `tmux attach -t =ccr-cloud`, or `tmux capture-pane -p -S -200 -t =ccr-cloud:` |
| A task's runner | `DATA_DIR/host/SESSION_ID/runner.log` |
| A task's files | `DATA_DIR/host/SESSION_ID/workspace` |
| Setup details | `npm run setup -- --verbose` |

## Check host resources

```sh
npm run resources
```

Setup, doctor and service startup run the same read-only check. It warns, and never
blocks or deletes anything, at these thresholds:

| Resource | Warning | Critically low |
|---|---|---|
| Memory | Under 1 GiB available, or under 2 GiB total | Under 256 MiB available |
| Disk | Under 5 GiB or 10% free | Under 1 GiB or 3% free |
| Inodes | Under 5% or 1,000 free | |
| CPU | One-minute load above twice the CPU count | |

If you see warnings, run fewer tasks at once or add capacity. Linux memory uses
`MemAvailable`. Disk checks cover the data directory, your repository roots and,
in Docker mode, default Docker storage.

## Capacity

The same commands, and the app, also say how many tasks this server can run at
once and what is likely to run out first. In the app it's on **Start your Manager**
in a new workspace, and in full under **Server settings → Capacity**; select
**Check again** to measure afresh.

The number is the smallest of:

| Limit | How it's counted |
|---|---|
| Memory | Total RAM, less 1 GB for the system, divided by the memory a task uses |
| CPU | Two tasks per CPU: tasks mostly wait on the model, but their builds and tests compete |
| Disk | Running tasks, plus how many more task workspaces fit on the disk tasks live on, keeping 5 GB free |
| inotify | The per-user inotify instance limit, less 16, at about 4 per task |

What a task uses is measured from the tasks the server already has: memory from
the running tasks (each runner's process group in host mode, its container in
Docker mode) and disk from the most recent tasks' workspaces, counting a task that
is building rather than an average. With nothing to measure, a typical task is
assumed: 1.5 GB of memory and 1.5 GB of disk. Setup and `npm run resources` always
use the typical task.

It also warns about specific risks:

| Risk | When |
|---|---|
| Little disk | Under 20 GB free on a checked filesystem (a warning, with how many more tasks fit), under 5 GB critical |
| Little memory | Under 4 GB of RAM, or under 1 GB available now (critical) |
| No swap | No swap on a host with under 16 GB of RAM: running out of memory kills a process, perhaps a task, instead of slowing down |
| inotify | A limit under 256 instances per user, 80% or more of them in use (critical), or under 65,536 watches. Raise them with `sudo sysctl fs.inotify.max_user_instances=1024` and `fs.inotify.max_user_watches=524288`, and add them to `/etc/sysctl.d` to keep them |
| CPU | One CPU, or a one-minute load above twice the CPU count |
| Tools | Docker mode without `docker` (critical); host mode without tmux (a note). With systemd and under 8 GB of RAM, a note that `CCR_CLOUD_HOST_CGROUP=systemd` and `CCR_CLOUD_HOST_TASK_MEMORY_MAX` can cap each task's memory |

The capacity check is advisory: it never blocks a task or deletes anything. To
free disk, retire finished tasks from the board's **Clean up finished tasks…**
([Retire and delete](https://console.uubright.com/docs/tasks/#retire-and-delete)).

## Rotating credentials

Each task snapshots its environment when it's created, and Resume reuses that
snapshot. After rotating an environment-based credential, start new tasks to pick
it up.

## Next steps

- [Failure and recovery](https://console.uubright.com/docs/reliability/)
- [Configuration](https://console.uubright.com/docs/configuration/)
- [Command line](https://console.uubright.com/docs/cli/)
- [Troubleshooting](https://console.uubright.com/docs/troubleshooting/)
