Self-host the Cloudroom core

On your computer (pick another name if my-cloudroom is taken):

ssh exe.dev new --name=my-cloudroom
ssh my-cloudroom.exe.xyz

All remaining commands run on the VM, as exedev.

Install the core#

Read Cloudroom's installer if you like, then run it with a pinned version:

curl -fsSL https://cloudroom.dev/install.sh -o install.sh
sudo bash install.sh --version 0.1.89

In about 15 seconds it installs Node.js 24, creates the cloudroom service account and the cloudroom-agent account the agents run as, writes a new token to /etc/cloudroom/core.env (root only), and starts the service on 127.0.0.1:9840. Expect Cloudroom core 0.1.89 is running.

Connect the agents to the LLM integration#

Set up Claude Code and Codex for the agent account, then tell the core where Codex is. Claude Code needs no core settings: the core finds it once ~/.claude exists.

sudo -iu cloudroom-agent exeuntu configure claude
sudo -iu cloudroom-agent exeuntu configure codex
sudo tee -a /etc/cloudroom/core.env >/dev/null <<'EOF'
CLOUDROOM_CODEX_BINARY=/usr/local/bin/codex
CLOUDROOM_CODEX_HOME=/home/cloudroom-agent/.codex
CLOUDROOM_CODEX_MODEL=gpt-6.1-sol
EOF
sudo systemctl restart cloudroom

Check both, with a helper that keeps the token out of the command line:

api() {
  sudo awk -F= '/^CLOUDROOM_TOKEN=/{print "header = \"Authorization: Bearer " $2 "\""}' /etc/cloudroom/core.env |
    curl --config - --silent --show-error --fail-with-body "$@"
}
sleep 3
api http://127.0.0.1:9840/v1/capabilities | jq -r '.harnesses[].id'

Expect codex and claude-code.

Run a test task#

api --json '{"request_id":"setup-test","harness":"claude-code"}' http://127.0.0.1:9840/v1/sessions >/dev/null
sleep 10
api --json '{"request_id":"hello","text":"Create hello.txt containing Hello from Cloudroom."}' \
  http://127.0.0.1:9840/v1/sessions/cr_setup-test/prompts >/dev/null
sleep 30
sudo cat /home/cloudroom-agent/hello.txt
api --json '{"request_id":"close-setup-test"}' http://127.0.0.1:9840/v1/sessions/cr_setup-test/close >/dev/null

Expect Hello from Cloudroom. If the file isn't there yet, wait and cat again.

Put the API on port 8000#

exe.dev's HTTPS proxy sends the VM's address to port 8000. nginx passes the core's API there and nothing else, without buffering, so the app's live event streams and terminals work. The core stays on localhost:

sudo tee /etc/nginx/sites-available/cloudroom >/dev/null <<'EOF'
map $http_upgrade $connection_upgrade { default upgrade; '' ''; }
server {
    listen 8000;
    listen [::]:8000;
    client_max_body_size 0;
    location /v1/ {
        proxy_pass http://127.0.0.1:9840;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_buffering off;
        proxy_request_buffering off;
        proxy_read_timeout 1d;
        proxy_send_timeout 1d;
    }
    location / { return 404; }
}
EOF
sudo ln -sf /etc/nginx/sites-available/cloudroom /etc/nginx/sites-enabled/cloudroom
sudo nginx -t && sudo systemctl enable --now nginx && sudo systemctl reload nginx
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/v1/ready
api http://127.0.0.1:8000/v1/ready

Expect 401 without the token, then {"ready":true} with it.

Set up nightly backups#

Each night at about 3:30 UTC, a timer archives the core's settings and history and the agents' home and /code to /var/backups/cloudroom, keeping two weeks:

sudo tee /etc/systemd/system/cloudroom-backup.service >/dev/null <<'EOF'
[Unit]
Description=Back up Cloudroom core

[Service]
Type=oneshot
UMask=0077
ExecStart=/bin/sh -c 'mkdir -p /var/backups/cloudroom && tar -czf /var/backups/cloudroom/cloudroom-$$(date +%%Y%%m%%d-%%H%%M).tar.gz -C / etc/cloudroom var/lib/cloudroom home/cloudroom-agent code && find /var/backups/cloudroom -name "cloudroom-*.tar.gz" -mtime +13 -delete'
EOF
sudo tee /etc/systemd/system/cloudroom-backup.timer >/dev/null <<'EOF'
[Unit]
Description=Nightly Cloudroom backup

[Timer]
OnCalendar=*-*-* 03:30:00
RandomizedDelaySec=30m
Persistent=true

[Install]
WantedBy=timers.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now cloudroom-backup.timer
sudo systemctl start cloudroom-backup.service
sudo sh -c 'tar -tzf "$(ls -t /var/backups/cloudroom/cloudroom-*.tar.gz | head -1)"' | grep -c core.env
systemctl list-timers cloudroom-backup.timer

Expect 1 and a scheduled next run. Then connect the app.

Everything lives in four places: /etc/cloudroom (settings and token), /var/lib/cloudroom (history), /home/cloudroom-agent (the agents' logins and settings) and /code (the agents' work). On the VM, take an archive now:

sudo systemctl start cloudroom-backup.service
sudo sh -c 'ls -t /var/backups/cloudroom/cloudroom-*.tar.gz | head -3'

The auto- folders beside them are the old binaries Cloudroom's updater keeps for its rollbacks.

Copy archives off the VM too, and keep them private: they hold the token and everything the agents wrote. On your computer:

ssh my-cloudroom.exe.xyz 'sudo sh -c "cat \$(ls -t /var/backups/cloudroom/cloudroom-*.tar.gz | head -1)"' > cloudroom-backup.tar.gz

To restore on the VM, replace BACKUP.tar.gz with the archive's name. On a new VM, run the install steps first, then restore over them:

sudo systemctl stop cloudroom &&
sudo tar -xzf /var/backups/cloudroom/BACKUP.tar.gz -C / &&
sudo systemctl start cloudroom

The app's threads and the agents' files come back, with the old token. Pushing work to Git as you go is still the best backup for code.

Cloudroom publishes core releases almost daily. Update the core and the app together. Pick a core-v version from the releases, take a backup, then, replacing X.Y.Z:

sudo systemctl start cloudroom-backup.service
cd ~ && v=X.Y.Z && a=$(uname -m)
curl -fsSLO https://github.com/davidondrej/cloudroom/releases/download/core-v$v/cloudroom-core-$v-linux-$a.tar.gz
mkdir core-$v && tar -xzf cloudroom-core-$v-linux-$a.tar.gz -C core-$v
sudo python3 core-$v/install/update.py upgrade "$PWD/core-$v"
sudo cat /var/lib/cloudroom-update/state.json

The updater only swaps the binary after 10 minutes without agent activity, then checks every session and rolls back on failure. It never downgrades. "result": "updated" means done. waiting means agents worked recently: run the last two commands again in 15 minutes (until then it answers Waiting before the next attempt.). A note previews: CalledProcessError is harmless: previews aren't set up on a self-hosted core.

Ask Shelley, or check on the VM:

systemctl is-active cloudroom nginx
sudo journalctl -u cloudroom -n 50 --no-pager
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/v1/ready

• The app can't connect? On the public URL, check the VM is public (ssh exe.dev share show my-cloudroom) and that you pasted the whole token. https://my-cloudroom.exe.xyz/v1/ready should answer {"error":"unauthorized"} in a browser: that's the core, without the token. A login page means the VM is still private.

• connect Claude Code before starting cloud work? /home/cloudroom-agent/.claude/settings.json is missing. Run sudo -iu cloudroom-agent exeuntu configure claude and restart the core.

• Codex isn't offered? The three CLOUDROOM_CODEX_ lines are missing from /etc/cloudroom/core.env. Add them and restart the core.

• An agent fails at once? Check the LLM integration: curl -s https://llm.int.exe.xyz/v1/models | jq -r '.data[].id'.

• Token leaked? Put a new one in place and reconnect the app:

  sudo sed -i "s/^CLOUDROOM_TOKEN=.*/CLOUDROOM_TOKEN=$(openssl rand -hex 32)/" /etc/cloudroom/core.env
  sudo systemctl restart cloudroom
  

• Disk filling up? The core warns agents below 5 GB free. Check df -h /, delete old folders under /code, or grow the disk with ssh exe.dev resize my-cloudroom --disk=100GB.