Getting started

Run your first ccr-cloud task in about five minutes. 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):

SHELL

claude -p "Reply OK"

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.

#1. Install and start the service

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

SHELL

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:

SHELL

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:

SHELL

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:

SHELL

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

Select New, then Scratch task.
Enter Reply OK and select Start task.
Wait for Claude's reply and the Ready status.
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 before adding a repository or phone access.

#Next steps

Work with repositories: start a task in a checkout already on your server.
Run and control tasks: choose permissions and a response style, answer approvals.
Access from your phone: pick one way to reach the server without an SSH tunnel.
How it works: what runs where, and what tasks can access.

Edit this page on GitHub ↗