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

> ## Agent Instructions
> 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, 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. 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.

# Agent-guided installation

> Install Roomote with the standard installer, including from a local Linux VM.

This page is the execution contract for an agent asked to follow the
[self-hosting guide](/self-hosting). 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:

| Current environment | Default path |
| - | - |
| Fresh Ubuntu or Debian server, VPS, or VM | Run the installer directly. |
| macOS | Create or reuse a full Ubuntu VM, then run the same installer inside it. Multipass is the documented default. |
| Windows | Create or reuse a full Ubuntu VM, then run the same installer inside it. Multipass is the documented default. |
| WSL2 or a container | Do not assume it is a suitable deployment host. Use a full Ubuntu VM or VPS unless the user explicitly chooses an unsupported experiment. |

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](/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 theme={null}
curl -fsSL https://get.roomote.dev -o /tmp/roomote-install.sh
sudo bash /tmp/roomote-install.sh \
  --domain roomote.example.com \
  --no-setup-url
```

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:

```sh theme={null}
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 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](/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, install Multipass and create the VM:

```sh theme={null}
brew install --cask multipass
multipass launch 24.04 --name roomote --cpus 4 --memory 8G --disk 60G
```

For Windows, install Multipass and create the same Ubuntu VM from PowerShell:

```powershell theme={null}
winget install -e --id Canonical.Multipass
multipass launch 24.04 --name roomote --cpus 4 --memory 8G --disk 60G
```

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.

Open a shell in the VM:

```sh theme={null}
multipass shell roomote
```

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.

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 theme={null}
curl -fsSL https://get.roomote.dev -o /tmp/roomote-install.sh
sudo bash /tmp/roomote-install.sh \
  --domain example.com \
  --tls-mode internal \
  --no-setup-url
```

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.

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](/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:

```sh theme={null}
sudo roomote status
sudo roomote logs [service...]
sudo roomote restart [service...]
sudo roomote backup
sudo roomote upgrade
sudo roomote rollback
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.