Skip to main content
Roomote is designed to run well on a single host behind a Caddy reverse proxy. The canonical, always up-to-date operator guide lives in SELF_HOSTING.md in the repository; this page summarizes the public setup path and the checks that usually matter first. Start here when you want an operator-managed deployment for your team. By the end of setup, you should have a reachable Roomote URL, sign-in, a source-control provider, an inference provider, at least one environment, and a first reviewable Roomote task.

​
One-command install

SSH into a fresh Ubuntu or Debian server (x86_64 or arm64, 4 GB+ RAM) and run: 
curl -fsSL https://get.roomote.dev | bash
The installer brings up the full stack from published images and prints a setup link. Open it in a browser and the wizard walks you through the rest: sign-in provider, source-control provider, inference provider and API key, communications provider, repositories, and a first task. No DNS setup is needed to try it out; pass --domain roomote.example.com for a production install on your own domain. Prefer to read what you are about to run as root? Download, inspect, then run the same script: 
curl -fsSL https://get.roomote.dev -o install.sh
less install.sh
sudo bash install.sh

​
Setup checklist

Have these ready before the wizard asks for them:
  • a public HTTPS URL for the deployment, especially when source-control or chat callbacks need to reach it
  • a sign-in provider for the people who will use the deployment
  • a source-control provider account with permission to install or configure the app for the repositories Roomote should reach
  • an inference provider API key, such as OpenRouter, Anthropic, or OpenAI
  • a communications provider workspace, such as Slack, Microsoft Teams, or Telegram, if your team wants to start work from chat
  • at least one repository that can become the first Roomote environment

​
Day-2 operations

The installer also sets up the roomote host CLI for common operations: 
roomote upgrade   # pull and roll out newer images
roomote rollback  # return to the release before the last upgrade
roomote backup    # create an encrypted deployment recovery bundle
roomote logs      # tail service logs
roomote backup prompts for a passphrase and writes a versioned .roomote bundle under /opt/roomote/backups. The bundle contains PostgreSQL, the deployment configuration and encryption/signing keys, local MinIO artifacts, schema metadata, and the exact deployed image identities. Store the passphrase separately in your secret manager; the backup cannot be restored without it. Use roomote backup --include-redis when queued work, BullMQ schedules, sessions, and other transient Redis state must survive. Backups briefly stop application writers (and active Docker task workers) so the included stores share a documented consistency point. If object storage is external, the bundle records its endpoint and bucket but does not copy its objects; keep a provider-level backup of that bucket. Restore only after installing Roomote on the replacement host: 
roomote restore /path/to/backup.roomote --yes
Restore verifies the encrypted bundle and checksums before replacing any state, restores the original .env (including ENCRYPTION_KEY), repopulates empty PostgreSQL/MinIO/Redis volumes, and starts the recorded Roomote release.

​
Upgrades and rollback

roomote upgrade is designed so a bad release cannot strand your deployment:
  • A backup comes first. Every upgrade creates an encrypted pre-upgrade bundle under /opt/roomote/backups before anything changes. Pass a passphrase with --backup-passphrase-file (or ROOMOTE_BACKUP_PASSPHRASE); otherwise one is generated and stored next to the bundle. Use --skip-backup to opt out.
  • Migrations run before services are replaced. Database migrations apply in a single transaction while the previous release keeps serving. If a migration fails, the schema rolls back, the previous configuration is restored, and the previous release stays up.
  • Rollback is one command. Every release’s schema keeps the previous release working, so roomote rollback re-deploys the prior release without touching the database. roomote upgrade <tag> does the same for any retained tag, and restoring the pre-upgrade bundle is the last-resort path that also rewinds data.
The supported rollback target is the release immediately before the current one. Check the running application version and applied schema migration at any time under Settings → Deployment → Diagnostics; both are also recorded in every backup bundle’s manifest.

​
Deployment modes

  • One-command install — deploy/install.sh on an existing server, using published GHCR images.
  • Local development — pnpm dev runs the services from your checkout with PM2 for fast source edits.
  • Production Compose with Caddy — docker-compose.production.yml adds a Caddy container as the HTTPS entrypoint for your app and preview domains, and runs the containerized stack in production mode with per-install secrets (locally or on a server).

​
Requirements

  • An inference provider API key (OpenRouter, Anthropic, OpenAI, and others).
  • A GitHub account — the setup wizard creates the GitHub App for you.
  • For Slack, Microsoft Teams, and Telegram: a workspace where you can install an app; the setup wizard prefills the Slack app manifest for you.

​
Verify the deployment

After setup, run a small task that uses the first environment. A healthy deployment should let you:
  • sign in from the public Roomote URL
  • connect source control and see the expected repositories
  • create or select an environment
  • start a task from the dashboard or chat
  • inspect the task transcript, logs, and any generated diff or artifact
  • open a preview when the task starts a web app

​
Common issues

  • Callbacks fail. Confirm the deployment has a public HTTPS URL and that the source-control or communications provider is using that exact URL.
  • The first task cannot clone a repository. Check source-control installation scope and repository permissions.
  • The agent cannot run useful commands. Add missing services, environment variables, setup commands, or tool versions to the environment.
  • Chat messages do not reach Roomote. Confirm the app is installed, invited to the channel, and using the current callback URL.