Skip to main content
This page is the execution contract for an agent asked to follow the self-hosting guide. Use Roomote’s standard Linux installer for both evaluation and production. Do not replace it with the repository’s local development or Compose workflow. Continue until a real Roomote task works. Running containers are an intermediate result, not a completed installation.

​
Choose the Linux host

Detect the current host before changing it, then use this default: Roomote publishes amd64 and arm64 images. The installer detects the Linux guest’s architecture, generates and preserves deployment secrets, installs Docker when needed, starts the published images, and installs the roomote host CLI. Do not clone or build Roomote from source unless the user intends to develop Roomote itself. Before making changes, report the selected Linux host, whether it is new or already contains Roomote, and the public-ingress plan. Pause for approval before installing host software, creating a VM, using sudo, creating public ingress, or replacing an existing deployment setting. Never delete an existing VM, 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, 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:
Omit --domain only for a short evaluation on a Linux host with a directly reachable public IPv4 address. The installer then uses a temporary sslip.io hostname. For production, use stable app and wildcard DNS with public TCP ports 80 and 443, or a named tunnel configured for the same stable hostnames. --no-setup-url suppresses the tokenized first-admin link in captured agent output. After the installation is healthy, the user must obtain that link in a separate trusted terminal by running:
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 installation from macOS or Windows

Use a full Linux VM and the standard installer. Prepare a stable public HTTPS URL using the home-network guide 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, install Multipass and create the VM:
For Windows, install Multipass and create the same Ubuntu VM from PowerShell:
Check Multipass requirements first. Installing host software and creating the VM require approval. Reuse a suitable existing Linux VM when available. Open a shell in the VM:
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. Keep tunnel tokens out of captured output; the user should complete account authorization. Once the route is configured, run the installer inside the VM with the chosen hostname. This example uses a tunnel with internal origin TLS:
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, 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. Do not replace the installer with development Compose files. The installer manages secrets, images, persistent state, migrations, Caddy, workers, and lifecycle commands.

​
Browser setup

Pause while the user opens the setup URL and completes the browser-owned steps:
  • create the first admin account
  • configure an inference provider or ChatGPT subscription
  • create and install the deployment’s source-control app
  • select the repositories Roomote agents may access
  • configure a sandbox provider and validate it where available
  • follow Run your first task; a saved environment is optional
For GitHub, the callback is <origin>/github/callback and the webhook is <origin>/api/webhooks/github. A loopback callback can support some OAuth flows, but GitHub cannot deliver webhooks to localhost; use the tunnel origin for the complete Roomote source-control workflow. The user must personally enter credentials and approve provider authorization. Do not request credentials, private keys, setup tokens, or tokenized URLs in the agent conversation.

​
Verify before declaring success

After browser setup, continue until all applicable checks pass:
  1. sudo roomote status reports the deployment services healthy.
  2. The public origin reaches Roomote and presents a publicly trusted browser certificate.
  3. Sign-in works and the expected repositories appear.
  4. Settings → Sandboxes → Validate environment succeeds for the selected 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.
Leave the operator with the public Roomote URL, the need to keep the host and any tunnel service running, and these commands: