> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roomote.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Self-hosting

> Run Roomote on your own server with the one-command installer or Docker Compose.

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`](https://github.com/RooCodeInc/Roomote/blob/develop/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:

```sh theme={null}
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:

```sh theme={null}
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:

```sh theme={null}
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:

```sh theme={null}
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.