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

Run your first ccr-cloud task. On a server where Claude Code already works, this
takes about five minutes; on a new server, install the prerequisites below first.
You'll start the service on your server, connect from your laptop over SSH, and have Claude reply in the browser.

This guide uses **host mode**: regular Claude Code running as your server user,
with that user's existing Claude and Git credentials. You don't need Docker, Claude
Code Router, a new API key or a domain.

## 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
- Claude Code installed and logged in for the user you'll run ccr-cloud as

Check Claude works for that user (this sends one small request to your model):

```sh
claude -p "Reply OK"
```

> [!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://ccr-cloud.uubright.com/docs/security/).

## 1. Install and start the service

In an SSH session on your server, as the user who runs Claude (not with `sudo`):

```sh
git clone https://github.com/thinkinginmath/ccr-cloud.git
cd ccr-cloud
npm ci
npm run setup -- --start
```

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.

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 never installs system packages or changes your Claude or Git credentials. If
it reports a missing tool, install it and run setup again.

## 2. Connect from your laptop

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 ccr-cloud's own
password. It isn't your Claude key or a GitHub token.

## 3. Run a scratch task

1. Select **New**, then **Scratch task**.
2. Enter `Reply OK` and select **Start task**.
3. Wait for Claude's reply and the **Ready** status.
4. Send a follow-up message. Then select **Stop session**, **Resume session**, and
   send one more message.

That's a complete round trip: the service, your browser connection and Claude'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://ccr-cloud.uubright.com/docs/troubleshooting/) before adding a repository or phone access.

## Next steps

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