[Docs] Guide Cloud and self-hosted users through their first task (#3382)

Author: mrubens

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.
+
+<Tip>
+  Start in the web dashboard. Slack and other communications providers are
+  optional and can be connected after your first task.
+</Tip>
+
+## 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.

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",

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
 

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.
+
+<Note>
+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.
+</Note>
+
+## 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: <command>` 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.