diff --git a/apps/docs/cloud.mdx b/apps/docs/cloud.mdx new file mode 100644 index 0000000000..e20aa8795b --- /dev/null +++ b/apps/docs/cloud.mdx @@ -0,0 +1,71 @@ +--- +title: Roomote Cloud +icon: cloud +description: Create a hosted Roomote deployment, connect your tools, and complete your first task. +--- + +Roomote Cloud runs an isolated Roomote deployment for you. Roomote manages +hosting, networking, task sandboxes, and upgrades. You use the web dashboard to +choose models, connect your repositories, and start work. + +By the end of this guide and [Run your first task](/first-task), you will +have a working deployment and a completed task whose result you can review. + +## Before you start + +For your first repository task, have: + +- a repository and an account with permission to authorize Roomote's access +- an inference option: managed Roomote inference when offered during setup, + or a supported subscription or inference provider API key +- any credentials or setup instructions your repository needs to build and + run, if they are not already documented in the repository + +You can use a browser on Windows, macOS, or Linux. Cloud provides the server +and sandbox infrastructure, so there is no local installation or domain setup +to complete. + + + Start in the web dashboard. Slack and other communications providers are + optional and can be connected after your first task. + + +## 1. Create your Cloud deployment + +[Sign up for Roomote Cloud](https://cloud.roomote.dev/sign-up), or +[sign in to the Cloud portal](https://cloud.roomote.dev/) if you already have +an account. Follow the portal's deployment setup, then open your Roomote +deployment when it is ready. + +The Cloud portal manages hosting. Your Roomote deployment is where you +complete product setup, configure providers, and run tasks. Keep its URL so +you can return directly to the dashboard. + +## 2. Complete setup and run a task + +Continue with [Run your first task](/first-task). Start at the account setup +step, or continue from your current step if it is already complete. + +The guide helps you create the administrator account, choose inference, +connect a repository, and run a small task. For Cloud: + +- **Inference:** choose the Roomote provider when offered, or connect your own + provider. Managed inference has a credit limit; see + [Managed Roomote inference](/models#managed-roomote-inference) for how it + works and how to add your own provider. +- **Sandboxes:** keep the sandbox provider provisioned for your Cloud + deployment. You do not need to create a separate sandbox provider account + to run your first task. +- **Repository access:** authorize the repositories you want Roomote to work + on. Cloud hosting does not grant Roomote access to them automatically. + +You have completed the getting-started path when Roomote can access your +repository, run work in a sandbox, and return a result you can inspect in the +dashboard. The first-task guide includes those checks and help for each step. + +## After your first task + +Connect [Slack or another communications provider](/communications) to start +and follow work from chat, or [invite your team](/users#create-invites) to use +the dashboard. Add an [environment](/environments) when you want reusable +repository setup, secrets, and instructions for future tasks. diff --git a/apps/docs/docs.json b/apps/docs/docs.json index 58db5a96ea..eead45df7d 100644 --- a/apps/docs/docs.json +++ b/apps/docs/docs.json @@ -5,13 +5,13 @@ "description": "Documentation for Roomote, the open, self-hostable platform for cloud coding agents.", "markdown": { "instructions": [ - "When helping someone deploy Roomote, distinguish self-hosting from contributing to Roomote. Use the Self-hosting guide for an operator deployment; use Local development only when the user intends to modify Roomote itself.", + "Start new users at /index to choose Roomote Cloud or self-hosting. Use /cloud for managed hosting and /self-hosting for an operator deployment, including home networks at /homelab. Both paths continue through /first-task. Use Local development only when the user intends to modify Roomote itself.", "When an agent is asked to follow /self-hosting or install Roomote autonomously, read and follow /self-hosting/agent-installation as the normative automation contract even though it is intentionally hidden from side navigation.", "Use the one-command Linux installer for both evaluation and production. On macOS or Windows, create or reuse a full Ubuntu VM and run the same installer inside it; do not replace the installer with the repository's development Compose files.", - "For a local VM without a stable public domain, create a temporary HTTPS tunnel, pass its hostname to the installer with internal origin TLS, and keep the tunnel running for OAuth callbacks and webhooks. Quick Tunnel hostnames are temporary and do not provide wildcard preview routing.", + "For a local VM, prepare a stable public HTTPS domain before connecting providers. Use a named tunnel with internal origin TLS or public DNS with ports 80/443 forwarded to the Linux host. Cloudflare Quick Tunnels do not support the Server-Sent Events Roomote uses; do not use them for the complete setup path.", "Run automated installs with --no-setup-url so the bootstrap token is not captured in the agent transcript. Let the user obtain the setup URL in a trusted terminal, enter credentials, and complete browser authorization.", "Proceed through safe, reversible setup and pause for privileged host or VM changes, public tunnel creation, credentials or browser authorization, durable external-account changes, destructive operations, existing-state conflicts, or when no documented safe default applies.", - "A setup is not complete when the services merely start. Verify sign-in, repository sync, one usable environment, and a real Roomote task that can clone and run a command; verify branch or pull-request delivery and previews when configured." + "A setup is not complete when the services merely start. Follow /first-task to verify sign-in, repository sync, and a real Roomote task that can clone and run a command. A saved environment is optional for a repository task. Verify branch or pull-request delivery and previews when configured; Slack and other communications providers are optional." ] }, "colors": { @@ -42,7 +42,22 @@ "groups": [ { "group": "Getting started", - "pages": ["index", "self-hosting", "homelab"] + "pages": [ + "index", + "cloud", + { + "group": "Self-hosted", + "icon": "server", + "root": "self-hosting", + "expanded": false, + "pages": [ + "homelab", + "self-hosting/platforms", + "self-hosting/operations" + ] + }, + "first-task" + ] }, { "group": "Using Roomote", @@ -77,10 +92,10 @@ "pages": [ { "group": "Models and inference", + "icon": "brain", "root": "models", "expanded": false, "pages": [ - "models", "providers/inference/amazon-bedrock", "providers/inference/anthropic", "providers/inference/azure-foundry", @@ -113,10 +128,10 @@ }, { "group": "Communications", + "icon": "messages-square", "root": "communications", "expanded": false, "pages": [ - "communications", "providers/communications/agentmail", "providers/communications/discord", "providers/communications/microsoft-teams", @@ -126,10 +141,10 @@ }, { "group": "Source control", + "icon": "git-merge", "root": "source-control", "expanded": false, "pages": [ - "source-control", "providers/source-control/azure-devops", "providers/source-control/bitbucket", "providers/source-control/gitea", @@ -139,10 +154,10 @@ }, { "group": "Sandboxes", + "icon": "cpu", "root": "compute", "expanded": false, "pages": [ - "compute", "providers/compute/azure", "providers/compute/blaxel", "providers/compute/box", diff --git a/apps/docs/environments.mdx b/apps/docs/environments.mdx index 52fa4ba351..0503614cd8 100644 --- a/apps/docs/environments.mdx +++ b/apps/docs/environments.mdx @@ -245,8 +245,8 @@ per-environment `env` map is stored in plaintext, so use deployment environment variables under **Settings > Environments > Deployment Environment Variables** for secret values. -See the [self-hosting guide](/self-hosting) for the compose mount pattern and -operational details. +See the [declarative environments reference](https://github.com/RooCodeInc/Roomote/blob/main/SELF_HOSTING.md#declarative-environments) +for the Compose mount pattern and operational details. ## Make verification possible diff --git a/apps/docs/first-task.mdx b/apps/docs/first-task.mdx new file mode 100644 index 0000000000..c8184b0cc1 --- /dev/null +++ b/apps/docs/first-task.mdx @@ -0,0 +1,200 @@ +--- +title: Run your first task +icon: play +description: Connect a model and repository, run a small task, and review the result in your browser. +--- + +Follow this guide after you can open your Roomote deployment. The steps are +the same for Roomote Cloud and self-hosted deployments, with hosting +differences called out below. By the end, you will have a Roomote task that +reads a repository, runs commands in a sandbox, and reports what it found. + +## Before you start + +Have these ready: + +- the deployment's initial setup link, or an administrator account if setup + has already started +- an inference provider account with usable credentials and available credit + or quota, unless you choose the Roomote inference offered during Cloud setup +- permission to connect one repository for the first task + +An inference provider supplies the model. A sandbox provider supplies the +isolated workspace where the agent edits files and runs commands. Both are +needed for the task in this guide. Cloud provisions a sandbox provider; +for a self-hosted deployment, the installer can configure Docker on your host. + + +You can start a conversation after connecting inference alone. Repository +access and a sandbox are needed for this repository task. Slack, other +communications providers, integrations, and automations are optional: you +can complete the whole guide in your browser. + + +## 1. Open your deployment and create your account + +Open the deployment link from the Cloud portal or your self-hosted installer. +Follow the account setup prompts. If you have already created the account, +sign in and continue from your current setup step. + +For a self-hosted deployment, **Use email/password** is the simplest account +option. You can choose Slack or Teams sign-in if you already intend to use +one of them. Use the setup token from the installer if Roomote requests it. + +**Check:** You can sign in to the Roomote dashboard and reach inference setup. + +## 2. Connect inference + +If you see **Configure inference**, choose **Use the Roomote provider** when +offered, or **Configure my own provider**. Otherwise, setup opens directly +at **Choose your LLM provider**. Select the service you use and follow its +connection instructions. For example, [OpenRouter](/providers/inference/openrouter) and +[Anthropic](/providers/inference/anthropic) use API keys; other providers may +use an account sign-in or a model endpoint. + +Enter credentials in the configuration form. Keep API keys and other secrets +out of the conversation. + +Roomote adds recommended models for supported providers. Start with those +defaults; you can change models later in **Settings > Models**. If Roomote +reports that the account has no credit or quota, resolve that with the +provider before starting work. + +**Check:** Roomote opens a setup conversation and sends an introductory +message. This conversation is saved, so you can return to it to continue +setup. + +## 3. Connect one repository + +In the setup conversation, choose your source-control provider and open its +configuration dialog. Follow the provider's authorization steps and grant +access to your chosen repository. Start with one small, existing repository +so you can easily inspect the first result. + +For [GitHub](/providers/source-control/github), **Create GitHub App** prepares +the app configuration for you. Complete the GitHub flow and install the app +on the account or organization that owns the repository. Other providers +have their own guides, including [GitLab](/providers/source-control/gitlab) +and [Gitea](/providers/source-control/gitea). + +**Check:** Return to the setup conversation and wait for Roomote to confirm +that your repositories are available. If the repository is missing, check +the provider connection and the app's repository permissions before +continuing. + +## 4. Choose a small first task + +Roomote next offers integrations with other tools. Select **Keep going** to +continue without connecting any for this guide. + +When Roomote offers starter tasks, choose **I'll type it myself** to skip +the suggested tasks. Those tasks can make changes and open pull +requests; the example below gives you a smaller first result to inspect. +Automation recommendations are optional and can wait until your first task +works. + +Enter this request in the message box in the same conversation, replacing +`owner/repository` with the repository you connected: + +```text +Run a task in a sandbox for owner/repository. Inspect the repository and +summarize its top-level folders and the dependency-install and test commands +already documented or defined in the project. Cite the files you used. If a +command is missing, say so instead of inventing one. + +Run git rev-parse --show-toplevel and git status --short in the repository +and include the results so I can confirm the workspace is working. Keep +this task read-only: do not edit files, commit, push, or open a pull request. +``` + +You do not need to create an environment for this first task. Roomote can +resolve the connected repository from your request. An +[environment](/environments) is useful when you want to save repeatable setup +commands, services, tool versions, or preview ports for later work. + +## 5. Confirm where the task will run + +If a sandbox provider is already configured, Roomote can start the task +without another setup step. Keep the provider provisioned for your Cloud +deployment or configured by your self-hosted installer. + +If Roomote asks for a sandbox, use its configuration controls to select and +configure a provider: + +- for a single-host self-hosted deployment, [Docker](/providers/compute/docker) + runs tasks on your server and needs no separate provider API key +- for a hosted sandbox, follow the chosen provider's credential and setup + instructions; see [Sandboxes](/compute) for the options + +You can also inspect or configure the default provider in **Settings > +Sandboxes**. Return to the conversation after saving and continue your +request if it has not started. + +For Docker, use **Validate environment** under **Settings > Sandboxes > +Local Docker** to check the daemon, worker image, and release archive. +Docker must also support writable-layer disk limits; the first task checks +that when its container starts. If it reports an unsupported disk limit, +follow the [Docker storage guidance](/providers/compute/docker#resource-and-network-isolation) +or choose a hosted sandbox provider. + +**Check:** A task appears in the conversation and begins preparing its +workspace. Open the task to follow progress. The first run may take longer +while images and repository dependencies are prepared. + +## 6. Review the result + +When the task finishes, open its workspace and check: + +1. The overview matches the repository, and the commands point back to real + project files. +2. The command output identifies the repository's sandbox checkout. An empty + `git status --short` result means the working tree is clean. +3. The task left the repository unchanged, as requested. + +Expand command entries in the task transcript to inspect their output. If +environment setup failed, open **Logs** and select the relevant +`Setup: ` entry. See [Review a task](/tasks) for the other review +tools. + +You now have a working path from your browser through inference, repository +access, and sandbox execution to a result you can inspect. Continue in the +same conversation with a small code change, ask Roomote to run the relevant +checks, and review its diff before requesting a pull request. Future work can +start from **New Session**; select a repository or environment when you +already know where it should run. + +## If your first task gets stuck + +| What you see | What to check | +| --- | --- | +| The conversation fails before answering | Check the saved provider in **Settings > Models**, its credentials, and available credit or quota. | +| Roomote cannot find or clone the repository | Check source-control authorization and repository permissions. On a self-hosted deployment, also check that the configured application URL is reachable for provider callbacks. | +| The task cannot start its sandbox | Check **Settings > Sandboxes**. For Docker, inspect host capacity and the error in the task logs. For a hosted provider, check its credentials and connectivity to your deployment. | +| A setup command or project check fails | Open the task logs. Add missing tools, services, or setup guidance through an [environment](/environments), then retry with that environment. | + +If a task failed to start, **Try in a new task** opens an editable request +with its original prompt and context. Correct the problem before launching +it again. + +## Continue setup later + +The setup conversation stays available when you leave the page. Its +configuration cards also leave the message composer available, so you can +keep talking while deciding what to connect. **Not now** skips an initial +offer; Roomote can offer that capability again when later work needs it. + +Only deployment administrators can configure providers through these +controls. Other members should ask an administrator to connect anything +their task needs. If you chose a suggested starter task and its launch +failed, ask Roomote to retry that item after fixing the problem; you do not +need to repeat setup. + +## Add more when you need it + +- [Create an environment](/environments) to make your project's setup reusable. +- [Connect Slack](/providers/communications/slack) or another communications + provider if you want to start and follow work outside the dashboard. +- [Connect integrations](/integrations/index) when a task needs context from + your other tools. +- [Set up automations](/automations) after you have verified the work you want + Roomote to repeat. diff --git a/apps/docs/homelab.mdx b/apps/docs/homelab.mdx index 4acefe7cea..e02d5ae632 100644 --- a/apps/docs/homelab.mdx +++ b/apps/docs/homelab.mdx @@ -1,253 +1,252 @@ --- -title: Homelab deployment +title: Home network and homelab icon: house-plug -description: Run Roomote on a Proxmox VM or another Linux server in your homelab. +description: Install Roomote on a computer or server at home, connect it, and run your first task. --- -Run Roomote on hardware you control with a dedicated Linux VM, private -administration over Tailscale, and a public HTTPS origin for provider callbacks -and task previews. +A homelab is a self-hosted deployment. You need one machine to run Roomote; +your other computers access it through a browser. For example, you can run it +on an Ubuntu computer and use it from Windows and a MacBook. -This guide uses **Proxmox VE with a Debian or Ubuntu VM** as the worked example. -Proxmox and Tailscale are not Roomote requirements: a bare-metal Linux server, -another hypervisor, WireGuard, or a conventional VPN can provide the same -roles. +This guide takes you through preparing that host, connecting your network, +and opening Roomote. Then [Run your first task](/first-task) walks through +account setup, inference, repository access, and a task you can review. + +## Before you start + +Prepare: + +- a dedicated Ubuntu 24.04 LTS or Debian 12+ machine, or a full Linux VM, + with administrator access; Windows and macOS can host a VM +- about 4 CPUs, 8 GB RAM, and 60 GB disk available to Roomote and its local + tasks, with more capacity for concurrent or Docker-heavy work +- a supported inference subscription or API key with available credit or quota +- permission to connect one repository for the first task +- a domain you control; the tunnel path also needs a Cloudflare account + managing that domain + +The host can be x86_64 or arm64. For local tasks, Docker must support +[writable-layer disk limits](/providers/compute/docker#resource-and-network-isolation). +The installer sets up Docker when needed, but does not configure disk quotas +for your filesystem. Choose local Docker if you have suitable storage, or +prepare credentials for a [hosted sandbox](/compute). A new Ubuntu VM with +its default disk setup can need additional storage configuration before +local tasks work. - Use a full virtual machine rather than an LXC container for the default Docker - sandbox provider. Roomote depends on Docker networking, cgroups, packet-filter - rules, and writable-layer quotas that are much easier to operate reliably in - a VM. LXC installations require host-specific privileged-container changes - and are not covered by this guide. + This guide uses a public HTTPS URL so external services can deliver + callbacks and webhooks. Hosting Roomote at home still needs this route for + the complete provider setup. A private LAN address or Tailscale address + alone cannot receive callbacks from services such as GitHub and Slack. + You sign in to Roomote at the public URL to use the dashboard. -## Plan the deployment +Slack, Proxmox, and Tailscale are optional. Start with the computer you +already have and complete your first task in the browser. -The recommended homelab shape separates private administration from public -application traffic: +## 1. Prepare one Linux host -- **Proxmox VM:** runs Roomote, its datastores, and the default Docker task - sandboxes -- **Tailscale:** provides private SSH and administrative access to the VM -- **Public HTTPS origin:** receives source-control and communications-provider - callbacks and serves links generated by Roomote -- **Caddy:** terminates traffic for the application and task preview hostnames +If you have a dedicated Ubuntu or Debian machine, open a terminal on it or +connect over SSH. Apply operating-system updates and keep the machine awake. +You do not need to create another VM. -Roomote supports x86_64 and arm64. The installer requires at least 4 GB of RAM. -For a deployment that runs Docker task sandboxes on the same host, start with: + + Create a full Ubuntu VM with + [Multipass](https://canonical.com/multipass/docs/latest/how-to-guides/install-multipass/). + Follow its installation instructions and check its operating-system and + virtualization requirements first. If you already have a suitable Linux + VM, use that instead. -| Resource | Recommended starting point | -| --- | --- | -| CPU | 4 vCPU, host CPU type | -| Memory | 8 GB | -| Disk | 60 GB or more on quota-capable storage | -| OS | Debian 12 or later, or Ubuntu 24.04 LTS | - -The default limit for each Docker task is 2 CPUs, 4 GiB of memory, and a 20 GiB -writable layer. Increase the VM resources for concurrent or Docker-heavy tasks, -or use a [hosted sandbox provider](/compute) so task workloads do not compete -with the Roomote services. - -## Create the Proxmox VM - -Create a VM from a Debian or Ubuntu cloud image or installation ISO: - -1. allocate at least 4 vCPU, 8 GB RAM, and 60 GB of disk -2. set the CPU type to `host` and use VirtIO for disk and networking -3. install and enable `qemu-guest-agent` -4. assign a DHCP reservation or static address on the LAN -5. enable SSH and apply operating-system updates - -A bare-metal mini PC, an existing Debian or Ubuntu server, or a VM on another -hypervisor works too. The important boundary is a clean Linux host where Docker -Engine and its networking and storage controls can operate normally. - -## Add private administration with Tailscale - -Install Tailscale on the VM using the -[official Linux instructions](https://tailscale.com/kb/1031/install-linux), then -confirm you can reach the host over its tailnet address before changing router -or firewall rules. Use Tailscale SSH or regular SSH over the tailnet for host -administration. - -Tailscale does not replace Roomote's public application origin. GitHub, Slack, -and other providers must reach callbacks from outside your tailnet. Live task -previews also use per-task hostnames, including wildcard preview DNS in the -normal production configuration. - - - Docker task sandboxes block private, link-local, shared-address, cloud - metadata, and Tailscale ranges by default. A repository hosted only on your - LAN or tailnet may be reachable from the VM but unreachable from a Roomote - task. Give self-hosted GitLab or Gitea a public, worker-reachable hostname - instead of disabling the sandbox network guard. - - -## Choose public ingress - -Choose one stable hostname before completing the setup wizard. Changing it -later also means updating source-control, sign-in, and communications-provider -redirect and webhook URLs. - -| Path | Best for | Tradeoffs | -| --- | --- | --- | -| Public DNS and port forwarding | Public IPv4, router control, and the simplest data path | Requires forwarding ports 80 and 443; dynamic addresses need DDNS | -| Cloudflare Tunnel | CGNAT or networks where inbound ports should stay closed | Requires tunnel and wildcard-hostname configuration | -| Tailscale Funnel | A limited public trial without router changes | Does not provide the wildcard hostname model needed for full live previews | - -### Public DNS and port forwarding - -Create DNS records for the application and wildcard previews: - -```text -roomote.example.com A/AAAA -*.roomote.example.com A/AAAA -``` + After installing Multipass, run these commands in PowerShell on Windows or + Terminal on macOS: + + ```sh + multipass launch 24.04 --name roomote --cpus 4 --memory 8G --disk 60G + multipass shell roomote + ``` + + The second command opens a shell inside Ubuntu. Run the Linux commands in + the rest of this guide there. For another terminal inside the same VM, + open a new host terminal and run `multipass shell roomote` again. + + Use the named-tunnel path in step 2 with this VM. Router port forwarding + would also require a VM network interface reachable from your router. + + Keep the computer and VM running while using Roomote. Use a full VM for + this deployment path; WSL2 and Docker Desktop are not substitutes for the + Linux host used by the installer. + + + + Create a Debian or Ubuntu VM with 4 vCPU, 8 GB RAM, and at least 60 GB disk. + Set the CPU type to `host`, use VirtIO for disk and networking, and install + `qemu-guest-agent`. Give the VM a DHCP reservation or static LAN address, + enable SSH, and apply operating-system updates. -Forward TCP ports 80 and 443 from the router to the VM, then run: + Use a full VM for Docker task sandboxes. LXC containers require additional + privileged-container, networking, and storage configuration and are not + covered by this guide. + + +Install the small tools used by the installer on the Linux host: ```sh -curl -fsSL https://get.roomote.dev | sudo bash -s -- \ - --domain roomote.example.com +sudo apt update +sudo apt install -y curl openssl less ca-certificates ``` -The installer defaults to flat preview hostnames such as -`task-port-preview.`, covered by the `*.` wildcard record. Pass -`--preview-domain preview.` when you prefer the dedicated -`task-port.preview.` namespace; that layout needs -`preview.` and `*.preview.` records instead of `*.`. -If the public address changes, configure DDNS for both records. This path does -not work behind carrier-grade NAT unless the ISP supplies a public address. +**Check:** You can open a terminal on the Linux host and run commands with +`sudo`. Ports 80 and 443 are available for Roomote's HTTPS server, Caddy. + +## 2. Connect your home network + +Use a **named Cloudflare Tunnel** if you want to avoid router changes, or if +you are using the Multipass VM above. Use **router port forwarding** if your +Linux host is reachable on the LAN and your ISP provides a public address. +Follow one tab, then continue to step 3. + + + + This path uses a domain managed through Cloudflare and keeps inbound + router ports closed. It works behind carrier-grade NAT, where your ISP + shares a public address and ordinary port forwarding cannot work. + + This example dedicates `example.com` to Roomote, with previews at + `*.example.com`. Replace it with a domain you control. This layout works + with Cloudflare's standard certificate. + + 1. Follow [Cloudflare's named tunnel setup](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/get-started/create-remote-tunnel/) + to install the connector as a service on the Linux host. + 2. Add the application hostname and preview wildcard as published routes + through the tunnel. Both must reach the same Caddy service: + + | Public hostname | Service on the Linux host | + | --- | --- | + | `example.com` | `https://localhost:443` | + | `*.example.com` | `https://localhost:443` | + + 3. Configure the HTTPS origin to trust Caddy's local CA, or enable + **No TLS Verify** for that local connection. Enable **Match SNI to + Host** on the wildcard route so preview requests reach Caddy with + the matching hostname. Confirm both DNS records route through the + tunnel and Cloudflare's public certificate is active. + 4. On the Linux host, download and inspect the installer, then run it + with your application hostname: + + ```sh + curl -fsSL https://get.roomote.dev -o install.sh + less install.sh + sudo bash install.sh --domain example.com --tls-mode internal + ``` + + Press `q` to leave `less`. Replace `example.com` with your domain. + Cloudflare serves public HTTPS and forwards traffic to Caddy. The + internal TLS setting applies to that private connection. Keep the tunnel + service running. + + If you choose a subdomain such as `roomote.example.com`, its preview + wildcard `*.roomote.example.com` needs additional certificate coverage. + See the [preview hostname reference](https://github.com/RooCodeInc/Roomote/blob/main/SELF_HOSTING.md#flat-preview-hostnames) + before choosing that layout. + + + Use this path if your router has a public IPv4 address and you can + forward ports. You need a domain with DNS records you can edit and a + Linux host whose LAN address the router can reach. For a VM, configure + its network accordingly or use the tunnel path. + + 1. Give the Linux host a DHCP reservation or static LAN address. + 2. Create these DNS records, replacing the domain and example IP with + your domain and home public IPv4 address: + + ```text + roomote.example.com A 203.0.113.10 + *.roomote.example.com A 203.0.113.10 + ``` + + These records should point directly to your home address. If you use + Cloudflare DNS, select **DNS only** for these records. + + 3. Forward TCP ports 80 and 443 from your router to the Linux host, and + allow them through the host firewall. Keep database and other + internal service ports private. + 4. On the Linux host, download and inspect the installer, then run it + with your application hostname: + + ```sh + curl -fsSL https://get.roomote.dev -o install.sh + less install.sh + sudo bash install.sh --domain roomote.example.com + ``` + + Press `q` to leave `less`. Caddy obtains the public HTTPS certificates. + If your home public address changes, set up dynamic DNS for both records. + If port forwarding cannot work because of carrier-grade NAT, choose the + tunnel path instead. + + + + + Cloudflare Quick Tunnels (`trycloudflare.com`) do not support the + [Server-Sent Events](https://developers.cloudflare.com/tunnel/get-started/quick-tunnels/#limitations) + used for Roomote's live updates. Use a named tunnel for this guide. If you + want to evaluate without your own domain, the + [public-server trial](/self-hosting#2-prepare-the-servers-url) uses an + automatic hostname on a server with a reachable public IPv4 address. + -### Cloudflare Tunnel +## 3. Open Roomote -Cloudflare Tunnel can publish Roomote without forwarding inbound router ports. -Install Roomote with Caddy's internal TLS mode because Cloudflare terminates the -public certificate: +When installation finishes, run this on the Linux host: ```sh -curl -fsSL https://get.roomote.dev | sudo bash -s -- \ - --domain roomote.example.com \ - --tls-mode internal +sudo roomote status ``` -Route both the application hostname and preview wildcard through the same Caddy -instance rather than routing directly to individual Roomote containers. Standard -Cloudflare certificates require Roomote's flat preview-hostname layout, which -the install command above already produces by default. Follow the canonical -[Cloudflare Tunnel and flat preview hostname configuration](https://github.com/RooCodeInc/Roomote/blob/main/SELF_HOSTING.md#flat-preview-hostnames) -for the tunnel ingress, origin TLS setting, and **Match SNI to Host** option -before testing or exposing task previews. - -### Tailscale Funnel - -Tailscale Funnel can expose a stable tailnet hostname to public callback -providers, but it does not support Roomote's normal wildcard preview hostname -layout. Treat it as a limited dashboard and callback trial, not the default -full deployment path. Use public DNS or Cloudflare Tunnel when users need live -task previews. - -## Let a local agent prepare the host - -Paste the following prompt into a local coding agent running on the VM or one -that can SSH to it. The agent prepares the host and installer; you complete -credential and authorization steps in Roomote's browser wizard. - -```text -Set up a self-hosted Roomote deployment on this homelab server. - -Safety and scope: -- Work only on a dedicated Debian 12+ or Ubuntu 24.04+ VM or bare-metal host. -- Stop if this is an LXC container or if fewer than 4 GB RAM or 40 GB free disk - are available. Warn me and ask before continuing if other production - workloads share the host. -- Explain changes before using sudo. Do not disable the firewall or expose - database, Redis, object-storage, API, or queue-dashboard ports. -- Never ask me to paste model, GitHub, Slack, or other provider secrets into - chat or the shell. Those belong in Roomote's browser setup wizard. - -Process: -1. Report the OS, architecture, CPU count, memory, free disk, default route, - public IPv4 detection result, and current Docker/storage configuration if - Docker is already installed. Do not change anything yet. -2. Ask me to choose one ingress path: public DNS plus ports 80/443, or - Cloudflare Tunnel. If I am behind CGNAT, recommend Cloudflare Tunnel. Ask for - the final application domain and optional preview domain. -3. Ask whether to install Tailscale for private SSH/admin access. If approved, - use Tailscale's official Linux package instructions and confirm access. Do - not treat the tailnet hostname as Roomote's public application origin. -4. For public DNS, tell me the exact app and wildcard DNS records (plus any - dedicated preview records if I chose a separate preview domain) and router - forwards I must create, then wait for me. Verify public DNS and ports - from outside the LAN where possible. For Cloudflare Tunnel, guide me through - creating the app and wildcard public hostnames without asking me to reveal a - tunnel token, and use Roomote's documented internal-TLS and flat-preview - configuration. -5. Download https://get.roomote.dev to a temporary file, show me the file path - and the exact installer flags you will use, and ask me to inspect it before - approval. Then run it with --domain and, for Cloudflare Tunnel, --tls-mode - internal. Do not write a new installer or manually recreate the Compose - stack. -6. Run `sudo roomote status`. If healthy, tell me to run `sudo roomote - setup-url` in a separate trusted terminal and open the result. Do not print, - capture, or repeat the tokenized URL in agent output or transcripts. Stop - while I complete sign-in, source control, inference, communications, and - environment setup in the browser. -7. After I confirm setup is complete, validate Docker's writable-layer quota - support, a small Roomote task, repository cloning, artifact upload, and a - configured preview. Summarize any failure and the relevant `roomote logs` - output without printing secrets. -``` +**Check:** The services are healthy. Open the setup link printed by the +installer in a browser on any of your computers. Keep that link private; it +lets you create the first administrator. You can retrieve it with +`sudo roomote setup-url` in your terminal. + +Also open the deployment's base URL from outside your home network, such as +on a phone with Wi-Fi turned off. Confirm the page loads with a valid HTTPS +certificate before connecting providers. -## Complete setup in the browser - -The installer sets up Docker, Compose, generated secrets, Caddy, the Roomote -services, a systemd unit, and the `roomote` host CLI. When it finishes, open the -tokenized setup URL it prints and configure: - -1. the first admin account -2. a source-control provider and repository access -3. a ChatGPT subscription or inference provider -4. Docker or a hosted sandbox provider -5. an optional communications provider such as Slack -6. the first environment and Roomote task - -Keep provider credentials in the setup wizard or your deployment secret store, -not in shell history or an agent conversation. - -## Verify the homelab path - -After setup: - -1. run `roomote status` on the VM and confirm the services are healthy -2. open the public Roomote URL from a device outside the home network -3. confirm the expected repositories appear in Roomote -4. validate the sandbox provider from **Settings > Sandboxes** -5. run a small task and confirm it clones, executes, and uploads an artifact -6. test a configured live preview from outside the home network -7. if configured, mention the Roomote app in Slack and confirm it replies - -Common homelab failures include: - -- **The public URL works on cellular but not on Wi-Fi.** The router may not - support hairpin NAT. Add split-horizon DNS for LAN clients or use a resolver - that returns the correct internal route. -- **An `sslip.io` hostname does not resolve on the LAN.** DNS-rebind protection - may reject names that resolve to private addresses. Use a domain you control - or allow the exact hostname in the local resolver. -- **Certificates never issue.** Confirm public DNS, router forwarding, and host - firewall rules for ports 80 and 443. With a tunnel, use `--tls-mode internal` - and check the tunnel-to-Caddy origin TLS settings. -- **Port forwarding has no effect.** Compare the router WAN address with an - external public-IP check. Different addresses usually indicate CGNAT; use a - tunnel or request a public address from the ISP. -- **A task cannot clone a LAN repository.** Use a public, worker-reachable - source-control hostname. Do not remove the sandbox private-network guard. - -## Back up and update - -Use `roomote backup`, `roomote upgrade`, and `roomote rollback` for supported -day-2 operations. A Proxmox snapshot is useful before host maintenance, but it -does not replace an encrypted Roomote backup stored off the VM with its -passphrase stored separately. See [Self-hosting](/self-hosting#day-2-operations) -for backup, restore, and upgrade behavior. +## 4. Complete setup and run a task + +Continue to **[Run your first task](/first-task)**. It walks through account +setup, inference, repository authorization, sandbox checks, and a small task +that proves Roomote can clone and run commands. You can do all of this from +your browser. + +After that task works, test a live preview if you configured wildcard +hostnames. Connect [Slack](/providers/communications/slack) or another +communications provider when you want to start work from chat. + +## If something does not work + +| What you see | What to check | +| --- | --- | +| The public URL works on cellular but not on home Wi-Fi | Your router may not support routing back to its public address. Use local DNS that maps the hostname to the Linux host, or use the tunnel path. | +| The tunnel reports an origin-connection error | Confirm Roomote is running on the same Linux host as the tunnel connector, and that its service points to `https://localhost:443`. | +| Certificates never issue | For port forwarding, check DNS and ports 80/443. For tunnels, use `--tls-mode internal` and the documented origin TLS settings. | +| The dashboard works but previews fail | Confirm the wildcard DNS or tunnel route and certificate coverage. | +| Port forwarding has no effect | Compare the router's WAN address with your public address. An upstream router or carrier-grade NAT can prevent forwarding; use a tunnel or request a public address from your ISP. | +| A task cannot clone a repository hosted on your LAN | Docker task sandboxes block private and Tailscale address ranges. Use a public, worker-reachable source-control hostname. See [Docker networking](/providers/compute/docker#resource-and-network-isolation). | +| A task reports an unsupported disk limit | Configure quota-capable Docker storage, or choose a hosted sandbox. See [Docker storage requirements](/providers/compute/docker#resource-and-network-isolation). | + +## Keep the deployment running + +Keep the host awake and the tunnel service running when one is used. Use +[Operate a self-hosted deployment](/self-hosting/operations) for backups and +updates. Store encrypted Roomote backups off the host and keep their +passphrases separately; VM snapshots are useful before maintenance but do not +replace those backups. + +For private administration, you can add Tailscale or another VPN for SSH +access. Tailscale's private address does not replace the public application +URL. Tailscale Funnel can serve a limited dashboard/callback trial, but it +does not provide the wildcard hostnames needed for full live previews. + +If a coding agent will prepare the host, give it the +[agent installation guide](/self-hosting/agent-installation). diff --git a/apps/docs/index.mdx b/apps/docs/index.mdx index b88b2d5cef..4a1d1b6a59 100644 --- a/apps/docs/index.mdx +++ b/apps/docs/index.mdx @@ -1,65 +1,64 @@ --- -title: Introduction +title: Getting started icon: book-open -description: Roomote is an open, self-hostable platform for cloud coding agents. +description: Choose Roomote Cloud or self-hosting, complete setup, and run your first task. --- -Roomote is an open, self-hostable platform for cloud coding agents. It runs -Roomote agents in isolated sandboxes, connects them to your repositories, and -lets your team start, follow, and review agent work from the web dashboard, -Slack, Microsoft Teams, Telegram, Discord, email, and your source-control -provider. +Roomote agents work on your repositories in isolated sandboxes and return +results you can review. Start, follow, and steer their work from the web +dashboard, with optional connections to your team's chat and other tools. -Use Roomote when agent work should be shared, reviewable, and available -outside one developer's editor. You keep control of the deployment, -repositories, inference provider, sandbox provider, and collaboration surfaces. +This guide takes you from choosing where Roomote runs to completing your first +repository task. Both hosting paths run the same Roomote product. -## Highlights +## 1. Choose where Roomote runs -- **Quick setup** — a one-command installer brings up the full stack, then a - guided conversation helps you connect providers and start useful work. -- **Self-hosted by default** — run Roomote on your own server and connect the - providers your team already uses. -- **Self-configuring environments** — Roomote agents prepare their own - sandboxes from your repositories and setup guidance. -- **Easy to use web dashboard** — launch, follow, and steer tasks from the - browser. -- **Model agnostic** — bring your own key for OpenRouter, Anthropic, OpenAI, - and other inference providers. -- **Source control integrations** — GitHub, GitLab, Gitea, Bitbucket Cloud, and - Azure DevOps. -- **Conversation surfaces** — Slack, Microsoft Teams, Telegram, Discord, and - email through AgentMail. -- **Choose your own sandbox provider** — including Docker-in-Docker on your - own host. + + + Roomote manages hosting, networking, sandboxes, and upgrades for your + isolated deployment. You choose inference, connect repositories, and + decide what work to run. + + + Run Roomote on your own hardware or infrastructure you control. You manage + the host, networking, sandboxes, and maintenance, then connect inference + and repositories. + + -## Where to go next +A home server or **homelab is a self-hosted deployment**. So is a deployment on +infrastructure you manage through a hosting provider, such as Railway or +Render. The self-hosting guide helps you choose a host and prepare it before +installation. -- [Self-hosting](/self-hosting) — run Roomote on your own server with the - one-command installer or Docker Compose. -- [How Roomote works](/how-roomote-works) — where work starts, how it - runs, and how results come back. -- [What to ask Roomote](/use-cases) — frame asks so tasks stay scoped, - useful, and reviewable. -- [Environments](/environments) — give Roomote the repositories, services, - secrets, and guidance it needs to run and verify work. -- [Review a task](/tasks) — inspect the transcript, logs, diffs, and - previews before anything ships. -- [Local development](/local-development) — set up the repository to - contribute to Roomote itself. -- [How a Roomote deployment runs](/architecture) — how requests become - reviewable results and which operator settings shape the path. +You access Roomote from a browser on Windows, macOS, or Linux. Each computer +does not need its own installation. + +## 2. Complete setup and run your first task + +Once your deployment is ready, follow [Run your first task](/first-task). +The guide walks through: + +1. Creating the administrator account and connecting inference, which gives + Roomote access to a model. +2. Connecting a repository and checking that a sandbox is ready to run work. +3. Running a small repository inspection task and reviewing the result. + +Have a repository you can authorize Roomote to access. For inference, use +managed Roomote inference when offered, or bring a supported subscription or +provider API key. The hosting guide explains what is already supplied. + + + Slack and other communications providers are optional. You can complete + your first task entirely in the web dashboard, then connect chat when you + want to use it. + ## License Roomote is released under the Fair Core License 1.0 (FCL-1.0-ALv2) — source-available, with each release converting to Apache-2.0 two years after it -is published. A deployment is free for up to 10 registered users; -adding more users requires a paid license key (Settings → Users, or the -`R_LICENSE_KEY` environment variable). You can [buy a self-hosted license on -Roomote Cloud](https://cloud.roomote.dev/sign-up); purchased keys are refreshed -annually from the Cloud portal, and licensed deployments report their current -user count for subscription billing. The license prohibits disabling or -circumventing the license key functionality. See -the [LICENSE](https://github.com/RooCodeInc/Roomote/blob/main/LICENSE) -file for details. +is published. Self-hosted deployments are free for up to 10 registered users; +more users require a paid license. See [License and seats](/users#license-and-seats) +for license setup and the +[LICENSE](https://github.com/RooCodeInc/Roomote/blob/main/LICENSE) for its terms. diff --git a/apps/docs/providers/compute/docker.mdx b/apps/docs/providers/compute/docker.mdx index 98c56b7a71..9b63a9d551 100644 --- a/apps/docs/providers/compute/docker.mdx +++ b/apps/docs/providers/compute/docker.mdx @@ -89,6 +89,19 @@ that enforce an equivalent host-level quota can explicitly set `DOCKER_WORKER_ALLOW_UNBOUNDED_DISK=true`; Roomote then logs a warning and starts without `--storage-opt size`. +Check storage before choosing Docker for a new self-hosted deployment. For +Docker's `overlay2` driver, per-container `size` limits require an XFS backing +filesystem mounted with project quotas (`pquota`). See +[Docker's storage-option requirements](https://docs.docker.com/reference/cli/docker/container/run/#set-storage-driver-options-per-container) +for the supported driver configurations. Allocating a larger VM disk alone +does not enable this support. + +On an existing Docker host, `sudo docker info` shows the storage driver, +backing filesystem, and Docker root directory. Prepare suitable storage +before running local tasks, or configure a [hosted sandbox provider](/compute) +in **Settings > Sandboxes**. The Roomote installer does not configure host +filesystem quotas. + Completed resumable tasks keep their stopped container and writable layer so a follow-up can restart the same workspace. Roomote retains at most 10 containers for 24 hours by default. Configure `DOCKER_STANDBY_MAX_COUNT` and @@ -136,6 +149,10 @@ repositories. The validation runs in the background worker service (the process with Docker socket access), so it reflects exactly what task boots will see. +Validation checks the daemon, image, and release archive. It does not test +writable-layer disk quotas; that check happens when a real task container +starts. Complete the small task above before considering Docker ready. + ## Common issues Before creating any sandbox resources, Roomote preflights the Docker diff --git a/apps/docs/self-hosting.mdx b/apps/docs/self-hosting.mdx index c7f327bcac..8072d0d050 100644 --- a/apps/docs/self-hosting.mdx +++ b/apps/docs/self-hosting.mdx @@ -1,347 +1,146 @@ --- title: Self-hosting icon: server -description: Deploy the cloud coding agent you own on Roomote Cloud or your own infrastructure. +description: Prepare your own host, install Roomote, and continue to your first task. --- -Roomote is the cloud coding agent you actually own. It runs your development -environment in isolated sandboxes, uses your repositories and tools, verifies -its work, and returns reviewable pull requests with previews when they apply. -Run the same single-tenant product on Roomote Cloud or infrastructure you -control. +Self-hosting means running Roomote on hardware or infrastructure you manage. +That includes a computer at home, a homelab, a rented server, or a hosting +platform such as Railway or Render. -Choose the fastest path for your team. Every deployment needs model inference: -use hosting-provisioned Roomote inference when it is offered, or connect a -ChatGPT subscription or inference provider API key. Source control is optional. -Connect it when Roomote should work on repositories, and configure a sandbox -provider only when you are ready to run coding work. Connect communications -providers and other tools when your team needs them. +Install Roomote once, then open its dashboard in a browser from your Windows, +macOS, or Linux computers. The host runs Roomote and, by default, the Docker +sandboxes where agents work on your repositories. + +This guide covers installation on a public Linux server. If your host is on +your home network, use [Home network and homelab](/homelab), which walks through +preparing a computer and giving Roomote a reachable URL. Both paths continue +to [Run your first task](/first-task). + +## Before you start + +For a deployment that runs tasks on the same host, prepare: + +| What you need | Starting point | +| --- | --- | +| Linux host | A dedicated Ubuntu 24.04 LTS or Debian 12+ server or full VM, with x86_64 or arm64 architecture and administrator (`sudo`) access. | +| Capacity | Start with 4 CPUs, 8 GB RAM, and 60 GB free disk. Allow more for concurrent tasks or projects that run Docker services. The application alone needs less; 4 GB leaves little room for local tasks. | +| Task execution | Choose Docker with [quota-capable storage](/providers/compute/docker#resource-and-network-isolation), or prepare credentials for a [hosted sandbox](/compute). A new Linux VM can need storage configuration before local tasks work. | +| Networking | A public HTTPS URL that browsers and provider callbacks can reach. Prepare the domain or tunnel before connecting providers. | +| Model access | A supported subscription, such as ChatGPT, or an inference provider API key with available credit or quota. | +| Repository access | One repository and permission to authorize Roomote's access, for the first task. | + +The installer sets up Docker and Compose when needed, the Roomote services, +databases, generated secrets, HTTPS through Caddy, and the `roomote` host CLI. +Choose a dedicated host with ports 80 and 443 available. - Asking a coding agent to install Roomote? Send it this page. Agents should - follow the [agent installation guide](/self-hosting/agent-installation). It - uses the standard installer on Linux and creates a Linux VM plus temporary - HTTPS ingress when the current machine is macOS or Windows. + You can create the first administrator with email and password. Slack and + other communications providers are optional; your first task can run + entirely through the web dashboard. -
- Deploy on Roomote Cloud - Deploy on Railway - Deploy to Render -
+## 1. Choose the matching installation path -## Choose your deployment +| Where Roomote will run | Follow this path | +| --- | --- | +| Public Ubuntu or Debian server | Continue below. | +| Computer or server on your home network | [Home network and homelab](/homelab), including Windows/macOS VM setup and a named tunnel. | +| Railway, Render, or another hosting platform | [Hosting platforms](/self-hosting/platforms), including provider accounts and template setup. | -- **Roomote Cloud** is the fastest way to get started. Your deployment remains - isolated while Roomote manages hosting, networking, sandboxes, and upgrades. -- **Railway** and **Render** provision the application, PostgreSQL, and Redis - from a template so you can run Roomote on managed infrastructure you control. -- **Your own server** gives you the most infrastructure control with the - one-command installer below. +If you are asking a coding agent to install Roomote, give it the +[agent installation guide](/self-hosting/agent-installation). -Running Roomote on Proxmox or another server at home? Follow the -[Homelab deployment guide](/homelab) for VM sizing, Tailscale administration, -public ingress, and a prompt that a local agent can follow. +## 2. Prepare the server's URL -By the end of setup, you should have a reachable Roomote URL, sign-in, and -managed Roomote inference or a connected inference provider. Repository access, -an environment, and a first reviewable task are optional until you choose coding -work. +Choose a domain such as `roomote.example.com`. In your DNS provider, create +these records, replacing the example address with your server's public IPv4 +address: -The canonical, always up-to-date guide for operating your own server lives in -[`SELF_HOSTING.md`](https://github.com/RooCodeInc/Roomote/blob/main/SELF_HOSTING.md) -in the repository. +```text +roomote.example.com A 203.0.113.10 +*.roomote.example.com A 203.0.113.10 +``` -## One-command install +The first record is for the dashboard and provider callbacks. The wildcard +record lets Roomote serve live task previews. Allow inbound TCP ports 80 and +443 in the server and hosting-provider firewalls so Caddy can obtain HTTPS +certificates and serve requests. The records should point directly to your +server; if you use Cloudflare DNS, select **DNS only** for these records. -SSH into a fresh Ubuntu or Debian server (x86_64 or arm64, 4 GB+ RAM) and run: +**Check:** Both records resolve to the server's public address, and the +firewalls allow ports 80 and 443. If your server is behind a home router or +cannot accept inbound connections, follow the [home-network guide](/homelab) +before installing. -```sh -curl -fsSL https://get.roomote.dev | sudo bash -``` + + If the server has a directly reachable public IPv4 address and ports 80 + and 443 are open, you can omit `--domain` from the install command below. + The installer uses an automatic `sslip.io` hostname with HTTPS. This is a + short evaluation option: the hostname depends on your IP address and shares + certificate rate limits with other `sslip.io` users. -The installer brings up the full stack from published images and prints a setup -link. Open it in a browser to create the first administrator and configure -inference. Roomote then opens a persistent setup conversation. You can connect -or skip source control, choose useful integrations, and continue talking without -a repository. With synchronized repositories, Roomote offers starter work and -then repository-aware automations. A sandbox is requested only when selected -coding work needs to launch. + A computer behind a home router still needs port forwarding or a tunnel. + Follow [Connect your home network](/homelab#2-connect-your-home-network) + to prepare a stable URL for that case. + -No DNS setup is needed to try it out; pass `--domain roomote.example.com` for a -production install on your own domain. +## 3. Install Roomote -Prefer to read what you are about to run as root? Download, inspect, then run -the same script: +Open a terminal on the Linux host, or SSH into it. Install the small tools +used by the installer: ```sh -curl -fsSL https://get.roomote.dev -o install.sh -less install.sh -sudo bash install.sh +sudo apt update +sudo apt install -y curl openssl less ca-certificates ``` -## Setup checklist - -Have these ready before setup asks for them: +Download and inspect the installer, then run it with your domain: -- 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, if Roomote should work on repositories -- a ChatGPT subscription or inference provider API key, such as OpenRouter, - Anthropic, or OpenAI, unless your host already provisioned Roomote inference -- a communications provider workspace, such as Slack, Microsoft Teams, - Telegram, or Discord, if your team wants to start work from chat -- at least one repository that can become the first Roomote environment, if you - want to launch coding work during setup +```sh +curl -fsSL https://get.roomote.dev -o install.sh +less install.sh +sudo bash install.sh --domain roomote.example.com +``` -## Day-2 operations +Press `q` to leave `less`. Replace `roomote.example.com` with the domain you +prepared. The installer downloads the published Roomote images and starts +the services. When it finishes, it prints a setup link for the first +administrator. Keep this link private. -The installer also sets up the `roomote` host CLI for common operations: +Run: ```sh -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 +sudo roomote status ``` -`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, the exact deployed image identities, and both the Memory volume -and isolated Memory database when the `brain` profile is enabled. Store the -passphrase separately in your secret manager; the backup cannot be restored -without it. - -Webhook and delivery lifecycle entries in `roomote logs` use single-line JSON -with an `event` field plus safe correlation fields such as provider, delivery, -Session, task, run, and job IDs. Search these entries to follow Telegram -messages and GitHub pull-request review activity from receipt through -persistence, dispatch, and final delivery. Message bodies, raw payloads, -credentials, signatures, and token-bearing URLs are excluded. - -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. - -Roomote exposes `/health/bullmq` for queue-processing health. It returns healthy -only when the background worker has recently processed its heartbeat job and no -Session event has remained queued for more than five minutes. Any overdue event -makes the check fail; authenticated error responses report the overdue count, -while unauthenticated responses omit diagnostics. Use it alongside container -liveness and `roomote logs`: a stale heartbeat or growing backlog can reveal a -worker process that is still running but no longer draining jobs. - -Restore only after installing Roomote on the replacement host: +**Check:** The services are healthy. Open the printed setup link in your +browser and confirm that the page loads over HTTPS. To retrieve the link +again, run `sudo roomote setup-url` in your terminal. -```sh -roomote restore /path/to/backup.roomote --yes -``` +If the page does not load, check the DNS records and ports from step 2, then +inspect `sudo roomote logs`. More troubleshooting is in +[Operate a self-hosted deployment](/self-hosting/operations#common-issues). -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. +## 4. Complete setup and run your first task -## Decision model on CPU (optional) +Continue to **[Run your first task](/first-task)** with the setup page open. +That guide takes you through creating the administrator account, connecting +inference and a repository, checking the sandbox provider, and running a +small task with a result you can inspect. -Roomote asks a decision model small typed questions: whether a turn is worth -remembering, who a thread reply is for, when a running task has news for the -user, which model a delegated task should use. With a TypeSafe key, Jev -answers them. Without one, the `judgment` profile runs a CPU decision model -beside the stack, so these features work with no external decision API and no -GPU. +The Linux installer selects Docker for task execution. Follow the Docker +checks in the first-task guide, including the storage requirements above. +You can choose a hosted sandbox provider if you want task workloads to run +elsewhere. -Add these to `.env`: +Your getting-started path is complete when you can sign in, access your +repository, run commands in a task sandbox, and inspect the result in the +dashboard. -```sh -COMPOSE_PROFILES=judgment # or append to an existing list -R_JUDGMENT_UPSTREAM_URL=http://judgment:8080 -R_JUDGMENT_MODEL=roomote # or choose it in Settings > Models -``` +## Day-2 operations -The sidecar serves -[`roomote/roomote-judgment-gliner`](https://huggingface.co/roomote/roomote-judgment-gliner), -a GLiNER 2.5 model fine-tuned on Roomote's decisions and trained only on -synthetic data. It downloads the model on first start and keeps it in the -`roomote_judgment_models` volume. Its model card lists the decisions it covers -and its accuracy; on real decisions it trails Jev by a few points, and Roomote -acts on a decision only when the model is confident and the decision is in its -evaluated policy. Unsupported decisions keep their existing safe fallback. To -serve a different checkpoint, set `JUDGMENT_MODEL` to a Hugging Face id or path -(and `JUDGMENT_HF_TOKEN` if it is private). - -The sidecar is reachable only on the stack's internal network; set -`R_JUDGMENT_UPSTREAM_API_KEY` as well to require a bearer token. - -Sizing: the container is capped at `JUDGMENT_MEMORY_LIMIT` (default `4g`) and -`JUDGMENT_CPUS` (default `4`). It uses about 1.5 GB, and on 4 cores a decision -takes about 0.3 to 1 second (p90 about 2 seconds). Decisions run one at a -time, so a burst of them queues and more cores make each one faster. - -The production install (`install.sh`) and the Railway, Render, and Coolify -templates carry the same service, opt-in like Memory: in the production -install it is the `judgment` profile, and in the templates it idles without -loading its model until `R_JUDGMENT_UPSTREAM_URL` points at it and the -Roomote judgment model is selected. Each template's README has the steps. - -## 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. The bundled - migration runner makes up to three total attempts after a transient Postgres - connection failure: the initial run plus at most two retries. If migration - still 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 ` does the same for any - retained tag, and restoring the pre-upgrade bundle is the last-resort path - that also rewinds data. - -Use `roomote upgrade` instead of updating application image references alone. -The command refreshes the release's Compose and Caddy configuration together; -mixing newer application images with an older Caddyfile can leave routes used -by the new controller unavailable until the deployment configuration is also -updated. - -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. - -Roomote surfaces release history and available updates in the web app: - -- **Admins** on self-hosted deployments see an update notice in the sidenav when - a newer GitHub release is available. The update dialog keeps that target and - its GitHub link visible even when the running image does not yet contain the - newer release's notes. Use `roomote upgrade` (or your image roll-forward - process) to install it. -- **Everyone** can open **About Roomote** and select **See all Roomote releases** - to browse the current and previous release notes bundled in the running - image, with the latest release expanded. After an upgrade, Roomote also shows - the latest "what's new" notice once. - -## Deployment modes - -- **One-command install** — `deploy/install.sh` on an existing server, using - published GHCR images. -- **Railway** — deploy the managed Railway template with hosted sandboxes. New - Railway signups get $20 in credit through [our referral link](https://railway.com?referralCode=roomote). -- **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 - -- Managed Roomote inference from an eligible host, or a ChatGPT subscription or - inference provider API key (OpenRouter, Anthropic, OpenAI, and others). -- An account with a supported source-control provider. For GitHub, the setup - conversation creates the GitHub App; other providers use their documented - OAuth or credential flow. -- For Slack, Microsoft Teams, Telegram, and Discord: a workspace or server where - you can install an app or bot; the setup assistant prefills the Slack app - manifest and creates Discord's installation link for you. - -## Verify the deployment - -After sign-in and inference are ready, setup continues entirely in a persistent -conversation with Roomote. Roomote suggests the next useful capability in a -recommended order and presents its trusted action card in the conversation. -Cards are non-blocking: the message composer remains available, and you can -continue talking without completing a card. Source control, integrations, -starter work, sandbox configuration, and automation recommendations can also be -offered later when a new request would benefit from them. Choosing **Not now** -advances the initial setup conversation; it does not permanently disable that -capability or prevent Roomote from suggesting it for a later goal. - -Detailed provider instructions and credential entry open in trusted dialogs; -Roomote never asks for credentials in chat. Only deployment administrators can -use configuration cards. Other members need an administrator to configure a -missing capability. - -After the source-control decision, Roomote normally offers integrations next. -The optional integrations card lists supported, disconnected tools and opens -their secure configuration without leaving the conversation. If you already -named a tool, Roomote can narrow the card to matching supported integrations. -If there are no eligible matches, setup moves on without showing suggestions. -Tools without a built-in connector are not presented as supported. Use -**Keep going** to move on without connecting; you can connect tools later in -Settings. Integration choices do not change the starter tasks offered. -Services that are also source-control, communications, inference, or sandbox -providers are excluded from this optional step; their separate setup is unchanged. -The Vercel deployments integration remains available separately from Vercel AI -Gateway inference. - -Without source control, setup completes after you connect or skip integrations; -no sandbox is required. Roomote continues with useful integration-based ideas -instead of repository starter tasks or automations. With synchronized -repositories, Roomote offers starter work after integrations. Choosing **Not -now** completes that initial decision without a sandbox. Selected starter work -waits for a sandbox, then Roomote -attempts every launch and completes setup even if one fails; ask Roomote to -retry a failed item. Automation analysis can begin after repository sync, but -recommendations appear only after integrations and the starter-task decision. -They never gate completion. - -After setup, run a small task that uses the first environment if you did not -start one from the starter list. 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.** For providers that use callbacks or webhooks, confirm the - deployment has a public HTTPS URL and that the provider is using that exact - URL. Discord uses its Gateway service instead of a public callback. -- **The first task cannot clone a repository.** Workers authenticate git with a - short-lived GitHub App installation token created when the run starts — they - do not read a `GH_TOKEN`/`GITHUB_TOKEN` from the container environment. If a - task fails with "No GitHub credentials are available", verify the GitHub App - is installed for the repository owner, the installation covers the - repository, and the repository appears in the source-control settings after a - sync. -- **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. -- **Roomote reports that local working storage is full.** Clean up container - storage, then recreate the affected application containers. Installer-managed - Compose deployments can raise `ROOMOTE_APP_TMPFS_SIZE` above its `512m` - default before recreating them; keep the limit within the host's available - memory. -- **Memory climbs for hours, or a service is OOM-killed under a container - memory limit.** Node sizes its heap from the memory it can see (the host's, - not the container's), so it defers garbage collection and lets memory drift - well above what the service needs; a container memory cap then kills the - process before Node ever feels pressure. Current app images cap each Node - service's heap by default (768 MB for web and api, 512 MB for controller and - bullmq, reduced to ~75% of the container's memory when a cgroup limit is - set). Set `NODE_OPTIONS=--max-old-space-size=` on a service to override - the default, or on older images to add the cap manually. - -## Agent-guided installation - -The [agent installation guide](/self-hosting/agent-installation) keeps the -one-command Linux installer as the single deployment path. On macOS or Windows, -an agent runs it inside a Linux VM and adds temporary HTTPS ingress for OAuth -callbacks and webhooks. +After the first task works, use [Operate a self-hosted deployment](/self-hosting/operations) +for backups, restore, upgrades, rollback, and troubleshooting. The +[operator reference](https://github.com/RooCodeInc/Roomote/blob/main/SELF_HOSTING.md) +covers advanced Compose configuration and deployment settings. diff --git a/apps/docs/self-hosting/agent-installation.mdx b/apps/docs/self-hosting/agent-installation.mdx index 5e71b68931..a44bd00d2b 100644 --- a/apps/docs/self-hosting/agent-installation.mdx +++ b/apps/docs/self-hosting/agent-installation.mdx @@ -1,5 +1,6 @@ --- title: Agent-guided installation +icon: terminal description: Install Roomote with the standard installer, including from a local Linux VM. --- @@ -36,6 +37,12 @@ deployment, or volume to obtain a clean state without explicit approval. ## Run the standard installer +Ensure `curl`, `openssl`, `less`, and `ca-certificates` are installed on the +Linux host. Check the [self-hosting prerequisites](/self-hosting#before-you-start), +including Docker storage support or credentials for a hosted sandbox, before +starting the installer. The installer selects Docker but does not prepare +quota-capable storage on the host. + On a Linux host with a stable public domain, use the normal production path: ```sh @@ -61,79 +68,69 @@ sudo roomote setup-url Do not run that command in a captured agent terminal, repeat its output, or ask the user to paste the link or token into chat. -## Local evaluation from macOS or Windows +## Local installation from macOS or Windows -A local trial still uses the standard installer. The only additional pieces are -a Linux VM for the deployment and temporary public HTTPS ingress for callbacks -and webhooks. The tunnel may run on the host or inside the VM as long as it can -reach the VM's Caddy ports. +Use a full Linux VM and the standard installer. Prepare a stable public HTTPS +URL using [the home-network guide](/homelab#2-connect-your-home-network) before +connecting providers. The named-tunnel path works with the VM commands below; +router port forwarding additionally needs a VM interface reachable on the LAN. -For macOS, the documented VM and tunnel clients are: +For macOS, install Multipass and create the VM: ```sh brew install --cask multipass -brew install cloudflared -multipass launch 24.04 --name roomote --cpus 4 --memory 6G --disk 40G +multipass launch 24.04 --name roomote --cpus 4 --memory 8G --disk 60G ``` -For Windows, install Multipass and `cloudflared`, then create the same Ubuntu -24.04 VM from PowerShell: +For Windows, install Multipass and create the same Ubuntu VM from PowerShell: ```powershell winget install -e --id Canonical.Multipass -winget install -e --id Cloudflare.cloudflared -multipass launch 24.04 --name roomote --cpus 4 --memory 6G --disk 40G +multipass launch 24.04 --name roomote --cpus 4 --memory 8G --disk 60G ``` -Installing these tools and creating the VM require approval. Reuse a suitable -existing Linux VM when one is already available instead of creating another. - -### Give the VM temporary HTTPS ingress - -Get the VM's address from the host: - -```sh -multipass exec roomote -- hostname -I -``` +Check [Multipass requirements](https://canonical.com/multipass/docs/latest/how-to-guides/install-multipass/) +first. Installing host software and creating the VM require approval. Reuse a +suitable existing Linux VM when available. -Start a Cloudflare Quick Tunnel on the host, replacing `` with the first -address returned above: +Open a shell in the VM: ```sh -cloudflared tunnel --url https://:443 --no-tls-verify +multipass shell roomote ``` -Keep this process running. It assigns a random -`https://.trycloudflare.com` origin. Starting the tunnel before Roomote is -installed can produce temporary origin-connection errors; the public hostname -is still the value needed by the installer. - -The private tunnel hop disables certificate verification because Caddy uses an -internal certificate in this evaluation topology. The browser and provider -connections to the public `trycloudflare.com` origin still use Cloudflare's -publicly trusted HTTPS certificate. +Install the Linux prerequisites there, then prepare the stable domain and +network route with the user. For a named Cloudflare Tunnel, run the connector +as a service inside the VM and route the application and preview hostnames to +Caddy. Follow the hostname, certificate, and origin TLS settings in the +[home-network guide](/homelab#2-connect-your-home-network). Keep tunnel tokens +out of captured output; the user should complete account authorization. -Open a shell in the VM and run the standard installer with the generated -hostname: +Once the route is configured, run the installer inside the VM with the +chosen hostname. This example uses a tunnel with internal origin TLS: ```sh -multipass shell roomote curl -fsSL https://get.roomote.dev -o /tmp/roomote-install.sh sudo bash /tmp/roomote-install.sh \ - --domain .trycloudflare.com \ + --domain example.com \ --tls-mode internal \ --no-setup-url ``` -Do not use the repository's development Compose files inside or outside the VM. -The installer remains responsible for secrets, images, persistent state, -migrations, Caddy, Docker workers, and lifecycle commands. +For public DNS and port forwarding, omit `--tls-mode internal`. Keep the host, +VM, and any tunnel service running while using Roomote. Use the same +application URL for setup and provider callback registrations. + +Cloudflare Quick Tunnels do not support +[Server-Sent Events](https://developers.cloudflare.com/tunnel/get-started/quick-tunnels/#limitations), +which Roomote uses for live updates. Do not use `trycloudflare.com` for the +complete setup path. A user without a domain can instead evaluate on a +server with a directly reachable public IPv4 address using the installer's +automatic hostname. -Quick Tunnels are intended only for evaluation. They have no uptime guarantee, -do not provide Roomote's wildcard preview hostnames, and receive a new hostname -when restarted. If the hostname changes, rerun the installer with the new -`--domain`, then update every provider callback and webhook registration before -continuing. Use a named tunnel or normal DNS for a durable deployment. +Do not replace the installer with development Compose files. The installer +manages secrets, images, persistent state, migrations, Caddy, workers, and +lifecycle commands. ## Browser setup @@ -143,8 +140,8 @@ Pause while the user opens the setup URL and completes the browser-owned steps: - configure an inference provider or ChatGPT subscription - create and install the deployment's source-control app - select the repositories Roomote agents may access -- validate the Docker sandbox provider -- create the first environment +- configure a sandbox provider and validate it where available +- follow [Run your first task](/first-task); a saved environment is optional For GitHub, the callback is `/github/callback` and the webhook is `/api/webhooks/github`. A loopback callback can support some OAuth @@ -164,17 +161,19 @@ After browser setup, continue until all applicable checks pass: certificate. 3. Sign-in works and the expected repositories appear. 4. **Settings → Sandboxes → Validate environment** succeeds for the selected - sandbox provider. + sandbox provider, when validation is available. Docker validation checks + the daemon, image, and release archive; the real task must also succeed + with the configured disk limit. 5. A small Roomote task clones a repository and runs a harmless command. 6. The task transcript, logs, and any generated artifact are accessible. 7. Configured callbacks and webhooks work through the public origin. 8. Branch or pull-request delivery works when the task requests repository changes. 9. A live preview works only when the chosen ingress provides the required - preview hostname coverage; do not require it from a Quick Tunnel. + preview hostname coverage. -Leave the operator with the public Roomote URL, the fact that a Quick Tunnel -must remain running when one is used, and these commands: +Leave the operator with the public Roomote URL, the need to keep the host and +any tunnel service running, and these commands: ```sh sudo roomote status diff --git a/apps/docs/self-hosting/operations.mdx b/apps/docs/self-hosting/operations.mdx new file mode 100644 index 0000000000..8f8ce3837f --- /dev/null +++ b/apps/docs/self-hosting/operations.mdx @@ -0,0 +1,181 @@ +--- +title: Operate a self-hosted deployment +icon: wrench +description: Back up, restore, update, and troubleshoot Roomote after your first task. +--- + +Use this guide after [installing Roomote](/self-hosting) and +[completing your first task](/first-task). These commands apply to deployments +created with the Linux installer. For a hosting platform, follow its +[deployment guide](/self-hosting/platforms) for lifecycle operations. + +Run host commands on the Linux machine running Roomote. Use `sudo` if your +account needs it to access the deployment. + +## Day-2 operations + +The installer also sets up the `roomote` host CLI for common operations: + +```sh +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, the exact deployed image identities, and both the Memory volume +and isolated Memory database when the `brain` profile is enabled. Store the +passphrase separately in your secret manager; the backup cannot be restored +without it. + +Webhook and delivery lifecycle entries in `roomote logs` use single-line JSON +with an `event` field plus safe correlation fields such as provider, delivery, +session, task, run, and job IDs. Search these entries to follow Telegram +messages and GitHub pull-request review activity from receipt through +persistence, dispatch, and final delivery. Message bodies, raw payloads, +credentials, signatures, and token-bearing URLs are excluded. + +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. + +Roomote exposes `/health/bullmq` for queue-processing health. It returns healthy +only when the background worker has recently processed its heartbeat job and no +session event has remained queued for more than five minutes. Any overdue event +makes the check fail; authenticated error responses report the overdue count, +while unauthenticated responses omit diagnostics. Use it alongside container +liveness and `roomote logs`: a stale heartbeat or growing backlog can reveal a +worker process that is still running but no longer draining jobs. + +Restore only after installing Roomote on the replacement host: + +```sh +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. The bundled + migration runner makes up to three total attempts after a transient Postgres + connection failure: the initial run plus at most two retries. If migration + still 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 ` does the same for any + retained tag, and restoring the pre-upgrade bundle is the last-resort path + that also rewinds data. + +Use `roomote upgrade` instead of updating application image references alone. +The command refreshes the release's Compose and Caddy configuration together; +mixing newer application images with an older Caddyfile can leave routes used +by the new controller unavailable until the deployment configuration is also +updated. + +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. + +Roomote surfaces release history and available updates in the web app: + +- **Admins** on self-hosted deployments see an update notice in the sidenav when + a newer GitHub release is available. The update dialog keeps that target and + its GitHub link visible even when the running image does not yet contain the + newer release's notes. Use `roomote upgrade` (or your image roll-forward + process) to install it. +- **Everyone** can open **About Roomote** and select **See all Roomote releases** + to browse the current and previous release notes bundled in the running + image, with the latest release expanded. After an upgrade, Roomote also shows + the latest "what's new" notice once. + +## Common issues + +- **Callbacks fail.** For providers that use callbacks or webhooks, confirm the + deployment has a public HTTPS URL and that the provider is using that exact + URL. Discord uses its Gateway service instead of a public callback. +- **The first task cannot clone a repository.** Workers authenticate git with a + short-lived GitHub App installation token created when the run starts — they + do not read a `GH_TOKEN`/`GITHUB_TOKEN` from the container environment. If a + task fails with "No GitHub credentials are available", verify the GitHub App + is installed for the repository owner, the installation covers the + repository, and the repository appears in the source-control settings after a + sync. +- **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. +- **Roomote reports that local working storage is full.** Clean up container + storage, then recreate the affected application containers. Installer-managed + Compose deployments can raise `ROOMOTE_APP_TMPFS_SIZE` above its `512m` + default before recreating them; keep the limit within the host's available + memory. +- **Memory climbs for hours, or a service is OOM-killed under a container + memory limit.** Node sizes its heap from the memory it can see (the host's, + not the container's), so it defers garbage collection and lets memory drift + well above what the service needs; a container memory cap then kills the + process before Node ever feels pressure. Current app images cap each Node + service's heap by default (768 MB for web and api, 512 MB for controller and + bullmq, reduced to ~75% of the container's memory when a cgroup limit is + set). Set `NODE_OPTIONS=--max-old-space-size=` on a service to override + the default, or on older images to add the cap manually. + +## Decision model on CPU (optional) + +Roomote asks a decision model small typed questions: whether a turn is worth +remembering, who a thread reply is for, when a running task has news for the +user, which model a delegated task should use. With a TypeSafe key, Jev +answers them. Without one, the `judgment` profile runs a CPU decision model +beside the stack, so these features work with no external decision API and no +GPU. + +Add these to `.env`: + +```sh +COMPOSE_PROFILES=judgment # or append to an existing list +R_JUDGMENT_UPSTREAM_URL=http://judgment:8080 +R_JUDGMENT_MODEL=roomote # or choose it in Settings > Models +``` + +The sidecar serves +[`roomote/roomote-judgment-gliner`](https://huggingface.co/roomote/roomote-judgment-gliner), +a GLiNER 2.5 model fine-tuned on Roomote's decisions and trained only on +synthetic data. It downloads the model on first start and keeps it in the +`roomote_judgment_models` volume. Its model card lists the decisions it covers +and its accuracy; on real decisions it trails Jev by a few points, and Roomote +acts on a decision only when the model is confident and the decision is in its +evaluated policy. Unsupported decisions keep their existing safe fallback. To +serve a different checkpoint, set `JUDGMENT_MODEL` to a Hugging Face id or path +(and `JUDGMENT_HF_TOKEN` if it is private). + +The sidecar is reachable only on the stack's internal network; set +`R_JUDGMENT_UPSTREAM_API_KEY` as well to require a bearer token. + +Sizing: the container is capped at `JUDGMENT_MEMORY_LIMIT` (default `4g`) and +`JUDGMENT_CPUS` (default `4`). It uses about 1.5 GB, and on 4 cores a decision +takes about 0.3 to 1 second (p90 about 2 seconds). Decisions run one at a +time, so a burst of them queues and more cores make each one faster. + +The production install (`install.sh`) and the Railway, Render, and Coolify +templates carry the same service, opt-in like Memory: in the production +install it is the `judgment` profile, and in the templates it idles without +loading its model until `R_JUDGMENT_UPSTREAM_URL` points at it and the +Roomote judgment model is selected. Each template's README has the steps. diff --git a/apps/docs/self-hosting/platforms.mdx b/apps/docs/self-hosting/platforms.mdx new file mode 100644 index 0000000000..31444965bc --- /dev/null +++ b/apps/docs/self-hosting/platforms.mdx @@ -0,0 +1,87 @@ +--- +title: Hosting platforms +icon: cloud-cog +description: Deploy Roomote in your Railway, Render, or other hosting account, then run your first task. +--- + +A deployment in your own hosting account is a self-hosted Roomote deployment. +The platform runs the infrastructure; you manage the deployment, credentials, +updates, and costs. If you want Roomote to manage the deployment for you, +follow [Roomote Cloud](/cloud). + +## Before you start + +Have these ready: + +- a hosting account with billing available for the template's services +- a supported inference subscription or provider API key with available credit +- permission to connect one repository for your first task +- a hosted sandbox account, such as Modal, E2B, or Daytona, for Railway or + Render; those platforms cannot run Roomote's local Docker task provider + +Hosting, model inference, and sandbox execution are separate resources. The +Railway and Render templates provision the application and its datastores. +You connect inference and sandbox credentials in Roomote after deployment. + +## 1. Deploy the application + +Choose your hosting platform: + + + + 1. Open the [stable Roomote template](https://railway.com/deploy/Rj2cFo?referralCode=roomote). + 2. Review the services and costs, then deploy it in your Railway account. + 3. Wait for the `web` and `api` services to report healthy. + 4. Open the web service's public domain at `/setup`. Copy `SETUP_TOKEN` + from the API service's **Variables** tab into the setup form. + + For a custom domain, set its full HTTPS URL in the template's `R_APP_URL` + input, attach the domain to the web service, and finish DNS before + opening setup on that domain. See the + [Railway deployment guide](https://github.com/RooCodeInc/Roomote/blob/main/deploy/railway/README.md) + for domain setup, service configuration, and maintenance. + + + 1. Open the [Roomote Blueprint](https://render.com/deploy?repo=https://github.com/RooCodeInc/Roomote). + 2. Review the services and costs, then deploy it in your Render account. + The Blueprint uses paid instances. + 3. Wait for `roomote-web` and `roomote-api` to report live. + 4. Open the web service's public domain at `/setup`. Copy `SETUP_TOKEN` + from the `roomote-shared` environment group into the setup form. + + See the + [Render deployment guide](https://github.com/RooCodeInc/Roomote/blob/main/deploy/render/README.md) + for first-boot troubleshooting, custom domains, and maintenance. + + + +Keep the setup token private. **Check:** The Roomote setup page loads over +HTTPS and accepts the token. + +## 2. Complete setup and run a task + +Continue to **[Run your first task](/first-task)**. Create the administrator +account, connect inference and a repository, and configure your hosted +sandbox provider when Roomote asks where the task should run. + +Modal is the template default for Railway and Render. Have its token pair +ready, or choose another supported provider and follow its setup instructions +in Roomote. A deployed application still needs a working sandbox provider to +run repository tasks. + +Live previews need additional wildcard-domain configuration on these +platforms. The first-task guide uses a repository inspection task, so you can +finish it before enabling previews. Follow your platform's deployment guide +when you are ready to add them. + +## Other deployment options + +- [Coolify](https://github.com/RooCodeInc/Roomote/blob/main/deploy/coolify/README.md) + runs the maintained Compose template on a server you manage. +- [Fly.io](https://github.com/RooCodeInc/Roomote/blob/main/deploy/fly/README.md) + provides a maintained deployment configuration with hosted sandboxes. +- [Advanced Compose configuration](https://github.com/RooCodeInc/Roomote/blob/main/SELF_HOSTING.md#production-compose-with-caddy) + is available for operators managing the stack directly. + +Each option continues to the same [first-task guide](/first-task) once its +Roomote URL is ready.