<!-- Source: https://console.uubright.com/docs/getting-started/ -->
# Getting started

This guide is for invited users installing the standalone server package on a Linux
host. You'll start the service, connect from your laptop over SSH, connect your
model, and run a first task in the browser. If you have the Mac app, start with the
[developer beta guide](https://console.uubright.com/docs/beta/); it can also [install a Linux host over SSH](https://console.uubright.com/docs/beta/#experimental-optional-add-a-remote-host-ssh)
and manage its connection for you.

This guide uses **host mode**: Claude Code or Codex running as your server user,
with that user's Git credentials. You don't need Docker or a domain.

If you already own an SSH server and are evaluating paid runtime management, see
the [existing-host flow](https://console.uubright.com/docs/operations/#managed-existing-host-phase-1-flow).

Claude Code can use your server user's existing login, an **Anthropic API key**,
**AWS Bedrock**, or a **Claude Code Router** gateway. Codex uses that user's
existing Codex login and provider configuration. Check that your chosen agent
can answer a prompt on the server before running a task in the browser.

## Before you begin

You need a Linux server you can SSH into, such as an EC2 instance, a VPS or a home
server, with:

- Node.js 22.18 or newer
- Git and tmux

Before running tasks, install and configure **at least one** agent for the server
user:

- [Claude Code](https://console.uubright.com/docs/bring-your-own-model/), with a working login, Anthropic API key,
  Bedrock credentials or CCR gateway; or
- [Codex CLI 0.163.0 or newer](https://console.uubright.com/docs/codex/#server-prerequisites), with working
  authentication and inference access. A Codex-only host needs no Claude Code
  installation or Anthropic, Bedrock or CCR credentials.

> [!WARNING]
> Tasks run as your server user and can use everything that user can: files, Git
> credentials, cloud credentials and network access. Use an account you trust for
> coding work, and review commands before approving them. See the
> [Security model](https://console.uubright.com/docs/security/).

## 1. Install and start the service

Request the standalone server package from [support@uubright.com](mailto:support@uubright.com)
if it wasn't included in your invitation. Follow the installation instructions
shipped with that package, as the account you use for coding work. From the
installed package directory, run `npm run setup -- --start`. You can install the
server before installing Claude Code or Codex; setup warns if an agent is missing.

Setup checks prerequisites and host resources, creates a private configuration in
`~/.local/share/ccr-cloud/server.env`, and starts the service in a detached tmux
session. When it prints **Service ready**, the service keeps running after you
close SSH. If no agent has model access yet, setup prints
**WARN No model connected yet**; you'll connect one in step 3.

For Claude Code, you can connect a model here with the same check the app runs.
For example, with an API key in a file:

```sh
npm run setup -- --start --anthropic-key-stdin < anthropic-key.txt
```

For Bedrock and CCR, see [Connect with setup](https://console.uubright.com/docs/bring-your-own-model/#connect-with-setup).

Setup also prints the exact commands for the next two steps. To have it print your
usual SSH host instead of `USER@SERVER`, set `CCR_CLOUD_SSH_TARGET`:

```sh
CCR_CLOUD_SSH_TARGET=my-ec2 npm run setup -- --start
```

Setup also says how many tasks this server can run at once and warns about what
would run out first, such as little free disk or a low inotify limit; the app shows
the same when you start your Manager. See [Capacity](https://console.uubright.com/docs/operations/#capacity).

Setup doesn't install system packages or change your Claude or Git credentials. If
it reports a missing tool, install it and run setup again.

## 2. Connect from your laptop

For this standalone installation, the service listens only on the server's
loopback address. Reach it through an SSH tunnel. In a **second terminal on your
laptop**:

```sh
ssh -N -L 8787:127.0.0.1:8787 USER@SERVER
```

Keep that terminal open and visit **http://localhost:8787**.

Back on the **server**, print your owner token:

```sh
sed -n 's/^CCR_CLOUD_TOKEN=//p' ~/.local/share/ccr-cloud/server.env
```

Paste it into **Access token** and select **Connect**. This token is uuBright Console's own
password. It isn't your Claude key or a GitHub token.

## 3. Connect your model

If neither Claude Code nor Codex is signed in on the server and no model is connected,
**Needs you** shows **Connect your model**. To use a Claude Code or Codex sign-in,
sign in once on the server (`claude`, then `/login`; or `codex login`) and choose
**Check again**. A Codex-only user can continue to step 4 after confirming the
[standalone CLI test](https://console.uubright.com/docs/codex/#server-prerequisites) succeeds. To connect a model
for Claude Code instead:

1. Select **Connect your model**.
2. Choose **Anthropic API key**, **AWS Bedrock** or **Claude Code Router**, and fill
   in its fields.
3. Select **Check and save**, and wait for **✓ Connected**. The check is free: it
   lists your models and uses no tokens.

If you see **✗ Not saved**, the message says what to fix. See
[Bring your own model](https://console.uubright.com/docs/bring-your-own-model/) for each option, what the checks
cost and where your credentials go.

## 4. Run a scratch task

1. Select **New**, then **Scratch task**.
2. If you use Codex, choose **Codex · server account** in New Task. Otherwise,
   choose Claude Code.
3. Enter `Reply OK` and select **Start task**. Wait for the chosen agent's reply
   and the **Done** status.
4. Send a follow-up message. Then open the task menu (⋯), select **End session**, confirm, select **Resume session**, and
   send one more message.

That's a complete round trip: the service, your browser connection and your agent's
model access all work. Tasks keep running when you close the browser or the SSH
tunnel; reopen the tunnel to pick them up again.

If the task fails, stay on this connection and see
[Troubleshooting](https://console.uubright.com/docs/troubleshooting/) before adding a repository or phone access.

## Next steps

- [Work with repositories](https://console.uubright.com/docs/repositories/): start a task in a checkout already on
  your server.
- [Run and control tasks](https://console.uubright.com/docs/tasks/): choose permissions and a response style,
  answer approvals.
- [Access from your phone](https://console.uubright.com/docs/remote-access/): pick one way to reach the server
  without an SSH tunnel.
- [How it works](https://console.uubright.com/docs/how-it-works/): what runs where, and what tasks can access.
