RooCodeInc · roomote-community · Aug 2, 2026 · Aug 2, 2026 · Aug 2, 2026
@@ -7,8 +7,8 @@ and assets all live in this directory and do not depend on `@roomote/web`.
 
 ## Structure
 
-- `docs.json` — the single source of truth for navigation, theme, branding, and
-  the navbar CTA.
+- `docs.json` — the source of truth for navigation, primary theme configuration,
+  and the navbar CTA.
 - `*.mdx` — the documentation pages. Each page is referenced by its file name
   (without extension) in the `docs.json` navigation. Add `icon` frontmatter
   with a Lucide icon name to show an icon for the page in the sidebar.

@@ -6,8 +6,8 @@ description: What anonymous usage data a Roomote deployment can share, how it is
 
 Roomote can share **anonymous telemetry** with the Roomote team to help
 improve the product. This is on by default, controlled entirely by
-deployment admins, and designed so that Roomote-generated identifiers and the
-default payload cannot identify your company, users, code, or repositories.
+deployment admins. Roomote-generated identifiers are random, and the default
+payload excludes direct company, user, code, and repository identifiers.
 
 ## What gets sent
 
@@ -23,8 +23,10 @@ When anonymous telemetry is enabled, your deployment sends:
   for the past week; configured provider types; and enabled built-in
   integrations.
 
-What is **never** sent: names, emails, repository names, task contents,
-prompts, code, tokens, or credentials.
+Roomote does not send names, emails, repository names, task contents, prompts,
+code, tokens, or credentials. Usage events do include configured model provider
+and model identifiers, so avoid identifying names in custom provider labels or
+model slugs.
 
 ## How it is identified
 

@@ -69,10 +69,11 @@ This is a good fit when:
 
 The tradeoff is that Docker uses the same host that runs the rest of your
 deployment. Heavy tasks can compete with the web app, API, database, queues, or
-other local services. Docker also depends on a restricted socket proxy that
-can create and manage worker containers on the host. The proxy is still
-privileged infrastructure, but the controller does not receive the raw host
-socket and unrelated Docker API sections remain blocked. Docker is not a
+other local services. Installer-managed production deployments use a restricted
+socket proxy that can create and manage worker containers on the host. The
+proxy is still privileged infrastructure, but the controller does not receive
+the raw host socket and unrelated Docker API sections remain blocked. Local
+development Compose mounts the host socket directly instead. Docker is not a
 multi-host scheduler.
 
 Hosted providers move the task sandbox into a provider-managed environment.

@@ -9,8 +9,8 @@ across tasks and automations. It reports the cost of recorded model usage in
 US dollars, so you can spot the environments, models, and work types that
 drive spend.
 
-Any signed-in deployment user can open **Analytics** from the dashboard, then
-select **Costs**.
+Deployment admins can open **Analytics** from the dashboard, then select
+**Costs**.
 
 ## What you can review
 

@@ -200,7 +200,7 @@ as per-task auth tokens or workspace paths.
 | `ZAI_REGION`                           | Provider key | Z.AI region: `global` (International) or `china`. Defaults to `global` when unset.                                                      |
 | `ZAI_CODING_PLAN_API_KEY`              | Provider key | Z.AI Coding Plan API key for `zai-coding-plan/...` models. Not a general platform key.                                                  |
 | `ZAI_CODING_PLAN_REGION`               | Provider key | Z.AI Coding Plan region: `global` (International) or `china`. Defaults to `global` when unset.                                          |
-| `OPENCODE_API_KEY`                     | Provider key | OpenCode Zen / Go API key.                                                                                                              |
+| `OPENCODE_API_KEY`                     | Provider key | OpenCode Zen API key.                                                                                                                   |
 | `GEMINI_API_KEY`                       | Provider key | Google Gemini API key. Can also be saved from **Settings > Models**.                                                                    |
 | `GOOGLE_GENERATIVE_AI_API_KEY`         | Provider key | Alternate Google/Gemini provider key forwarded when configured or inferred.                                                             |
 | `AWS_BEARER_TOKEN_BEDROCK`             | Provider key | Amazon Bedrock Mantle API key. Can also be saved from **Settings > Models**.                                                            |
@@ -241,16 +241,24 @@ as per-task auth tokens or workspace paths.
 | `MODAL_ENDPOINT`                     | Optional          | Modal endpoint override.                                                                                                                 |
 | `MODAL_ENVIRONMENT`                  | Optional          | Modal environment name.                                                                                                                  |
 | `MODAL_APP_NAME`                     | Optional          | Modal app name override.                                                                                                                 |
+| `MODAL_BASE_IMAGE_REF`               | Optional          | Base worker image reference used when provisioning Modal sandboxes.                                                                      |
+| `MODAL_REGISTRY_USERNAME`            | Optional          | Username for pulling a private Modal base image.                                                                                          |
+| `MODAL_REGISTRY_PASSWORD`            | Optional          | Password or token for pulling a private Modal base image.                                                                                 |
+| `MODAL_ECR_OIDC_ROLE_ARN`            | Optional          | AWS IAM role ARN used for OIDC-authenticated pulls from Amazon ECR.                                                                       |
+| `MODAL_ECR_REGION`                   | Optional          | AWS region for the ECR registry used with `MODAL_ECR_OIDC_ROLE_ARN`.                                                                      |
 | `MODAL_REGIONS`                      | Optional          | Comma-separated Modal sandbox placement regions (for example `us` or `us-west`). Unset keeps Modal default placement.                    |
 | `MODAL_VM_MEMORY_MIB`                | Optional          | Memory allocated to Modal VM sandboxes used for nested Docker workloads. Defaults to `8192` MiB.                                         |
 | `E2B_API_KEY`                        | E2B               | E2B API key. Can also be saved from **Settings > Sandboxes**.                                                                            |
+| `E2B_TEMPLATE_ID`                    | E2B               | Provisioned worker template ID. Saved automatically by UI setup; required for environment-only setup.                                    |
 | `E2B_DOMAIN`                         | Optional          | E2B domain for self-hosted or custom E2B clusters.                                                                                       |
 | `E2B_MAX_SANDBOX_TIMEOUT_MS`         | Optional          | Maximum E2B sandbox timeout Roomote will request. Defaults to one hour.                                                                  |
 | `DAYTONA_API_KEY`                    | Daytona           | Daytona API key. Can also be saved from **Settings > Sandboxes**.                                                                        |
 | `DAYTONA_API_URL`                    | Optional          | Daytona API URL override.                                                                                                                |
 | `DAYTONA_TARGET`                     | Optional          | Daytona target or region.                                                                                                                |
+| `DAYTONA_SNAPSHOT_NAME`              | Daytona           | Provisioned worker snapshot name. Saved automatically by UI setup; required for environment-only setup.                                  |
 | `BL_API_KEY`                         | Blaxel            | Blaxel API key. Can also be saved from **Settings > Sandboxes**.                                                                         |
 | `BL_WORKSPACE`                       | Blaxel            | Blaxel workspace name.                                                                                                                   |
+| `BLAXEL_IMAGE`                       | Blaxel            | Provisioned worker image name. Saved automatically by UI setup; required for environment-only setup.                                     |
 | `BLAXEL_REGION`                      | Optional          | Blaxel sandbox placement region. Unset lets Blaxel choose the closest region.                                                            |
 | `BLAXEL_STANDBY_MAX_COUNT`           | Optional          | Maximum Blaxel standby sandboxes retained for resume. Defaults to `25`; `0` disables retention.                                          |
 | `BLAXEL_STANDBY_MAX_AGE_HOURS`       | Optional          | Maximum age of a Blaxel standby sandbox. Defaults to `168`, capped at `168`.                                                             |
@@ -403,10 +411,11 @@ apply semantics.
 
 ## Environment variables versus environment settings
 
-Roomote also has **environment variables** inside **Settings > Environments**.
-Those are task workspace variables: they are made available to Roomote tasks
-running in that environment.
+Roomote also has per-environment **environment variables** inside **Settings >
+Environments**. Those task workspace variables are stored with that environment
+and configure the codebase Roomote is working on.
 
-This page is about deployment configuration variables. Deployment variables
-configure Roomote itself; environment variables inside an environment configure
-the codebase Roomote is working on.
+The encrypted deployment variables managed under **Deployment Environment
+Variables** can configure Roomote services and are also available to tasks in
+every environment. Per-environment values can reference them as `$KEY` or
+`${KEY}`, which keeps raw secrets out of environment definitions.
@@ -145,9 +145,10 @@ Keep commands focused on setup, not final verification. Put test expectations
 in agent instructions when you want Roomote to run them before finishing a
 task, and include the exact command, package, or path when it matters.
 
-Use **Don't block setup even if it fails** only for helpful-but-optional
-steps. If the app cannot run without the command, let setup fail so the issue
-is visible.
+Repository setup runs in the background and records command failures as
+readiness warnings, so a task can begin before setup finishes. Review the setup
+status and logs before relying on a failed step; **Don't block setup even if it
+fails** does not currently change whether an ordinary task can start.
 
 ## Use an existing Docker setup
 
@@ -156,12 +157,15 @@ a **Docker project** (`docker_projects` in YAML) instead of duplicating that
 setup as Roomote-managed services. A project can use one or more Compose files
 or build a single Dockerfile. Roomote starts it after the repository is cloned
 and waits for its services to become healthy before repository setup commands
-run.
+run where the sandbox supports health checks. Blaxel starts Compose services
+without the health wait.
 
 Map container ports to named environment ports when a service should have a
 live preview. Compose mappings also identify the service that owns the port.
-Startup is required by default; mark a project optional only when tasks can
-still work usefully without it.
+Startup is required by default. A required project's failure stops later Docker
+projects, but ordinary tasks surface background setup failures as readiness
+warnings rather than blocking task start. Mark a project optional when later
+projects should still start after it fails.
 
 Docker projects are supported by all sandbox providers. They are isolated with
 the task and are removed when the task sandbox is destroyed. They are still
@@ -217,15 +221,15 @@ on the next restart (every overwrite is kept in version history). Removing a
 definition never deletes the environment; it just returns it to normal manual
 management.
 
-Definitions may reference repositories that are not linked yet; the
-environment is created anyway and repository mappings backfill on the next
-startup after linking. Keep secrets out of definition files — the
-per-environment `env` map is stored in plaintext, so use deployment
-environment variables under **Settings > Environments > Deployment Environment
-Variables** for secret values.
+Definitions that reference repositories not yet linked to the deployment are
+skipped. Link every repository, then restart Roomote to apply the definition.
+Keep secrets out of definition files: the per-environment `env` map is stored
+in plaintext. Store secrets as encrypted deployment variables under **Settings
+> Environments > Deployment Environment Variables**, then reference them as
+`$KEY` or `${KEY}` from the environment definition.
 
-See the [self-hosting guide](/self-hosting) for the compose mount pattern and
-operational details.
+See [Mount declarative environments](/self-hosting#mount-declarative-environments)
+for the Compose pattern.
 
 ## Make verification possible
 

@@ -201,7 +201,7 @@ starting long-running services.
 | `cwd`               | string  | no       | Alias for `working_dir`.                                                                                        |
 | `timeout`           | number  | no       | Seconds before the command is killed. Defaults to `600`.                                                        |
 | `retries`           | integer | no       | Extra attempts for a failing command, with a 1-second delay. Use only for idempotent commands. Defaults to `0`. |
-| `continue_on_error` | boolean | no       | When `true`, setup continues even if this command fails. Defaults to `false`.                                   |
+| `continue_on_error` | boolean | no       | Accepted command metadata. Ordinary task setup currently records command failures as warnings and continues regardless. Defaults to `false`. |
 | `detached`          | boolean | no       | Run in the background under supervision. Use for long-running servers. Defaults to `false`.                     |
 | `logfile`           | string  | no       | Path to capture stdout and stderr. Used with `detached: true`.                                                  |
 
@@ -211,8 +211,8 @@ Guidance:
   before finishing" expectations in `agentInstructions` instead.
 - use `detached: true` with a `logfile` for servers such as `pnpm dev`, so the
   process keeps running and its output is debuggable.
-- use `continue_on_error: true` only for helpful-but-optional steps. If the app
-  cannot run without a command, let it fail so the problem is visible.
+- repository setup runs in the background for ordinary tasks. Check setup
+  status and logs for readiness warnings before relying on a failed command.
 
 ## Services
 
@@ -242,8 +242,9 @@ A service name cannot collide with a port name in the same environment.
 
 `docker_projects` runs Docker Compose or Dockerfile definitions already owned
 by a configured repository. Roomote validates the Compose model, builds images,
-starts services with `docker compose up --wait`, and treats startup as required
-unless `required: false` is set.
+and starts services with `docker compose up --wait` where health checks are
+supported. Blaxel starts Compose services without `--wait` because it does not
+support Docker health checks.
 
 Common fields:
 
@@ -255,7 +256,7 @@ Common fields:
 | `working_dir`             | string                    | no       | Relative directory inside the repository. Defaults to `.`.                 |
 | `env`                     | map                       | no       | Variables passed to Compose. Deployment-variable references are supported. |
 | `ports`                   | list                      | no       | Maps container ports to names from the top-level `ports` list.             |
-| `required`                | boolean                   | no       | Fail task startup when the project fails. Defaults to `true`.              |
+| `required`                | boolean                   | no       | Stop later Docker projects when this project fails. Ordinary tasks report the background failure as a readiness warning. Defaults to `true`. |
 | `startup_timeout_seconds` | integer                   | no       | Build and health-wait timeout. Defaults to 600, maximum 3600.              |
 
 For `type: compose`, `files` is a required list of relative Compose file paths.
@@ -333,11 +334,11 @@ ports:
 
 ## Environment variables and tool versions
 
-`env` provides workspace-level variables that every task can read. These are
-workspace variables for the code Roomote is working on, distinct from the
-[deployment environment variables](/environment-variables) that configure
-Roomote itself. Secrets are typically added through the editor rather than
-committed to a definition you share.
+`env` provides workspace-level variables that every task can read. The map is
+stored with the environment definition, so do not put raw secrets in it.
+[Deployment environment variables](/environment-variables) are encrypted and
+available to tasks in every environment as well as to Roomote services. Store
+secrets there, then reference them from `env` as `$KEY` or `${KEY}`.
 
 Tool versions can be set at two levels:
 

@@ -10,8 +10,9 @@ threads where you start or continue a Roomote task.
 Support varies by chat provider. The web app, Slack, and Telegram can read the
 formats below. Discord supports images and a smaller text and code subset, but
 not Office documents, PDFs, or presentations. Microsoft Teams currently
-supports image attachments only. Slack can also describe one supported video
-attachment per message.
+supports image attachments only. On Slack, Roomote accepts the first supported
+video attachment per message, describes it, and appends the result to the task
+prompt.
 
 Use attachments when the file itself is the fastest way to show the problem: a
 bug report export, a config file, a markdown handoff, a spreadsheet, or a PDF
@@ -34,8 +35,8 @@ If the attachments are large, Roomote reads them in the order you attach them
 and applies a shared text budget so the task stays responsive. Very large
 earlier files can leave later files included by name only.
 
-Text-extracted files are limited to 8 MB each. Image, video, and provider
-transport limits vary by surface.
+Text-extracted files are limited to 8 MB each. Image and provider transport
+limits vary by surface.
 
 ## Accepted file types