diff --git a/apps/docs/README.md b/apps/docs/README.md index 94c7dc8b..dcaaea11 100644 --- a/apps/docs/README.md +++ b/apps/docs/README.md @@ -15,7 +15,7 @@ and assets all live in this directory and do not depend on `@roomote/web`. - `roomote.css` — Roomote brand styling (Monaspace Neon code font, lime CTA, rounded surfaces). Mintlify auto-loads CSS placed at the workspace root. - `logo/` — light and dark Roomote wordmark logos used in the navbar. -- `favicon.svg` — the Roomote mark used as the site favicon. +- `favicon.png` — the Roomote mark used as the site favicon. - `fonts/` — the locally bundled Monaspace Neon code font (DM Sans is loaded by Mintlify via the `docs.json` font family reference). ## Local development diff --git a/apps/docs/anonymous-analytics.mdx b/apps/docs/anonymous-analytics.mdx index aabb3f0b..b2053d7c 100644 --- a/apps/docs/anonymous-analytics.mdx +++ b/apps/docs/anonymous-analytics.mdx @@ -17,10 +17,11 @@ When anonymous telemetry is enabled, your deployment sends: never actual URLs or IDs) and product events such as tasks being created or settling as completed, failed, or canceled, with non-identifying facts like the harness, model, source surface, and sandbox provider used. -- **A daily instance report** — aggregate counts only: number of users, - environments, and connected repositories, task and token totals for the - past day, which provider types are configured, and which built-in - integrations are enabled. +- **A daily instance report** — aggregate deployment metadata and usage: + setup timestamps; counts of users, environments, and connected repositories; + task, model, token, and cost totals for the past day; pull-request statistics + 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. diff --git a/apps/docs/environment-variables.mdx b/apps/docs/environment-variables.mdx index f263d73b..6ee6f644 100644 --- a/apps/docs/environment-variables.mdx +++ b/apps/docs/environment-variables.mdx @@ -1,5 +1,6 @@ --- title: Environment Variables +icon: variable description: 'Understand Roomote environment-variable precedence, production recommendations, and supported deployment configuration keys.' --- @@ -120,6 +121,9 @@ as per-task auth tokens or workspace paths. | `R_PUBLIC_URL` | Local callbacks | Stable public HTTPS origin used by local development for OAuth and webhook callbacks. | | `R_APP_URL` | Production | Public web app origin. Workers and integrations use it for links back to Roomote. | | `TRPC_URL` | Production | API/tRPC origin used by workers and services. In single-origin production, this is often the app URL plus `/_roomote-api`. | +| `R_PING_BASE_URL` | Optional | Base URL for anonymous telemetry and version checks. Defaults to `https://ping.roomote.dev`. | +| `R_INSTANCE_ID` | Optional | Stable anonymous deployment identifier sent with telemetry and version checks. Use a random, non-identifying value when overriding it. | +| `ROOMOTE_FORCE_TELEMETRY` | Development only | Force-enables telemetry in development or preview environments when a Ping endpoint is explicitly configured. | | `R_CLOUD_ENABLED` | Roomote Cloud only | Deployment-managed switch for Roomote Cloud behavior, including required anonymous analytics and Cloud support integrations. Do not set this for self-hosted deployments. | | `R_GITHUB_APP_SLUG` | GitHub setup | GitHub App slug used by server-rendered setup and GitHub integration flows. | | `SETUP_TOKEN` | Required (non-local) | One-time bootstrap token that admits the first admin at `/setup`. Required on every non-local deployment — tokenless bootstrap is allowed only when `NODE_ENV` is not `production` and `R_APP_ENV` is `development`, so anything running with `NODE_ENV=production` needs it. Without it, first-admin bootstrap stays closed so nobody can claim the founding-admin slot by reaching the URL first. Optional only in local development. | @@ -214,7 +218,7 @@ as per-task auth tokens or workspace paths. | Env var | Required | Used for | | ------------------------------------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -| `DEFAULT_COMPUTE_PROVIDER` | Optional | Runtime default sandbox provider when no admin default is saved. Supported values are `docker`, `modal`, `e2b`, `daytona`, `blaxel`, and `azure`. | +| `DEFAULT_COMPUTE_PROVIDER` | Optional | Runtime default sandbox provider when no admin default is saved. Supported values are `docker`, `modal`, `e2b`, `daytona`, `azure`, and the Roomote Cloud-only `roomote`. | | `EXCLUDED_COMPUTE_PROVIDERS` | Optional | Comma-separated provider IDs to hide or exclude from default selection. | | `DOCKER_WORKER_IMAGE` | Optional | Worker image used by Docker. In production, prefer an immutable registry-qualified tag. | | `ROOMOTE_WORKER_IMAGE_REPO` | Optional | Registry repository used to derive the worker image from `RELEASE_VERSION` when `DOCKER_WORKER_IMAGE` is unset. | diff --git a/apps/docs/environments/definition.mdx b/apps/docs/environments/definition.mdx index b407c7d4..9df82f8d 100644 --- a/apps/docs/environments/definition.mdx +++ b/apps/docs/environments/definition.mdx @@ -45,7 +45,7 @@ same setup. The concepts map closely: | Setup steps | [`onCreateCommand` / `postCreateCommand`](https://containers.dev/implementors/json_reference/#lifecycle-scripts) | Repository `commands` | | Forwarded ports | [`forwardPorts` / `portsAttributes`](https://containers.dev/implementors/json_reference/#port-attributes) | `ports` | | Workspace env vars | [`containerEnv` / `remoteEnv`](https://containers.dev/implementors/json_reference/#variables-in-devcontainer-json) | `env` (and per-command `env`) | -| Tool customizations | [`customizations`](https://containers.dev/supporting-tools) | `agentInstructions`, `mcpServers`, `skills` | +| Tool customizations | [`customizations`](https://containers.dev/supporting) | `agentInstructions`, `mcpServers`, `skills` | The important difference: **Roomote uses its own schema and does not read `devcontainer.json`.** The comparison is conceptual. If a repository already has @@ -173,7 +173,7 @@ cloned onto the shared workspace. | Field | Type | Required | Notes | | --------------- | ------ | -------- | ----------------------------------------------------------------- | -| `repository` | string | yes | `owner/repo` format. | +| `repository` | string | yes | Slash-separated full name, such as `owner/repo`; some providers use additional segments. | | `branch` | string | no | Branch to check out. Defaults to the repository's default branch. | | `tool_versions` | map | no | Repo-local tool fallbacks installed via mise. | | `commands` | list | no | Setup commands for this repository. See [Commands](#commands). | @@ -182,7 +182,7 @@ Keep the first environment focused. One repository, or a small set that must be cloned together, sets up faster and is easier to debug than a large multi-repo environment. -All repositories in one environment must belong to the same source-control +GitHub repositories in one environment must belong to the same GitHub App installation. ### Commands diff --git a/apps/docs/file-attachments.mdx b/apps/docs/file-attachments.mdx index 06bccd99..c45cff23 100644 --- a/apps/docs/file-attachments.mdx +++ b/apps/docs/file-attachments.mdx @@ -7,10 +7,11 @@ description: Attach files that Roomote can read directly in chat and the web app Roomote can read supported file attachments from the web app and from chat threads where you start or continue a Roomote task. -Support varies by chat provider. Slack, Telegram, and Discord can read the -text-extractable formats below, while Microsoft Teams currently supports image -attachments only. Slack can also describe one supported video attachment per -message. +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. 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 @@ -52,8 +53,9 @@ transport limits vary by surface. Text, code, spreadsheet, document, and presentation files are read into the task as attachment context. Images are passed through as image inputs so -Roomote can inspect them directly, except `.svg` files, which are read as text -markup instead of being sent as image inputs. +Roomote can inspect them directly. `.svg` files are normally read as text +markup, but Discord treats an SVG reported with the `image/svg+xml` content type +as an image input. That means you can ask things like: diff --git a/apps/docs/how-roomote-works.mdx b/apps/docs/how-roomote-works.mdx index 663d7ac8..8a7e1fb6 100644 --- a/apps/docs/how-roomote-works.mdx +++ b/apps/docs/how-roomote-works.mdx @@ -43,8 +43,8 @@ manage these in the web app under **Automations** — see | Surface | How work starts | Where updates appear | | ------------- | ---------------------------------------------------------- | --------------------------------------- | | Slack | Mention Roomote or reply in an active Roomote thread | Slack thread and task view | -| Teams | Mention the bot in a channel, group chat, or personal chat | Teams thread and task view | -| Telegram | Mention the bot in a group chat or private chat | Telegram chat and task view | +| Teams | Mention the bot in a channel or group chat, or message it directly in a personal chat | Teams thread and task view | +| Telegram | Mention the bot in a group chat, or message it directly in a private chat | Telegram chat and task view | | Discord | Mention the bot in a server or send it a direct message | Discord thread, forum post, or DM | | Web dashboard | Submit a prompt from **Home** | Task view in Roomote | | Linear | Start an agent session or mention Roomote on an issue | Linear activity and task view | diff --git a/apps/docs/integrations/index.mdx b/apps/docs/integrations/index.mdx index 4e49a298..afecc1d9 100644 --- a/apps/docs/integrations/index.mdx +++ b/apps/docs/integrations/index.mdx @@ -78,7 +78,7 @@ sense for one workspace, repository set, or self-hosted service. For most teams, this order works well: 1. the required providers: - [Comms](/communications), [Source Control](/environments), + [Comms](/communications), [Source Control](/source-control), [Inference](/models), and [Sandboxes](/compute) 2. one task-tracking integration, such as Linear, Jira, or Asana, if your team already works there diff --git a/apps/docs/integrations/linear.mdx b/apps/docs/integrations/linear.mdx index 1bd1ceea..237d70b9 100644 --- a/apps/docs/integrations/linear.mdx +++ b/apps/docs/integrations/linear.mdx @@ -26,7 +26,10 @@ priority, or discussion. Select **Connect Linear**, approve the app in Linear, and return to Roomote. Deployments that provide `R_LINEAR_CLIENT_ID`, `R_LINEAR_CLIENT_SECRET`, and `R_LINEAR_WEBHOOK_SECRET` in the runtime - environment continue to use those values and skip the in-app setup. + environment skip Roomote's credential-entry flow, but the Linear app must + still use `https:///api/mcp-oauth/callback` as its OAuth + redirect URI and `https:///api/webhooks/linear` as its + `AgentSessionEvent` webhook URL. A deployment administrator can return to **Settings > Integrations** and diff --git a/apps/docs/integrations/snowflake.mdx b/apps/docs/integrations/snowflake.mdx index b45b4433..1490ab1c 100644 --- a/apps/docs/integrations/snowflake.mdx +++ b/apps/docs/integrations/snowflake.mdx @@ -15,7 +15,17 @@ questions or support an investigation. ## How setup works -Admins connect Snowflake from **Settings > Integrations**. +Admins connect Snowflake from **Settings > Integrations** with an account +identifier, username, role, and PKCS8 PEM-encoded private key. Add the matching +public key to the Snowflake user first. Supply the private-key passphrase too +when the key is encrypted. + + + The `execute_sql` tool can run any statement permitted by the configured + Snowflake role, including statements that change data or schema. Use a + dedicated least-privilege role, preferably read-only when tasks only need + warehouse context. + ## What to expect diff --git a/apps/docs/local-development.mdx b/apps/docs/local-development.mdx index de61a748..9ac4a035 100644 --- a/apps/docs/local-development.mdx +++ b/apps/docs/local-development.mdx @@ -20,13 +20,15 @@ The full contributor walkthrough lives in the repository - **mise** — manages the repository toolchain (Node.js, pnpm, and friends). - **OpenCode CLI** — provides the `opencode` binary used to run tasks (`npm install -g opencode-ai`). -- **ngrok** — optional, only when you point `R_PUBLIC_URL` at an ngrok - domain; any public HTTPS URL works. +- **A public HTTPS URL** — set `R_PUBLIC_URL` to a URL that reaches local port + 13000. An ngrok domain, Cloudflare Tunnel, Tailscale Funnel, or your own + domain works. Install ngrok only when you use an ngrok domain. ## Install and run ```sh mise install && pnpm install +printf 'R_PUBLIC_URL=https://your-public-domain.example\n' >> .env.local pnpm dev ``` @@ -41,9 +43,9 @@ therefore upload screenshots and other artifacts without direct access to your machine's localhost ports. An explicit `S3_PRESIGN_ENDPOINT` continues to take precedence when you use separate object storage. -Use a public HTTPS URL, such as an ngrok domain, when testing provider -callbacks from source control or communications providers. Local-only URLs are -fine for dashboard work that does not need external callbacks. +`pnpm dev` requires the public HTTPS URL even when you only plan to use the +dashboard, because the development stack resolves callback and artifact URLs +during startup. Useful process-management commands: diff --git a/apps/docs/models.mdx b/apps/docs/models.mdx index 11cd2905..959f84f6 100644 --- a/apps/docs/models.mdx +++ b/apps/docs/models.mdx @@ -152,12 +152,13 @@ R_CODE_REVIEW_MODEL=openrouter/openai/gpt-5.6-sol R_EXPLORE_MODEL=openrouter/openai/gpt-5.6-luna ``` -Roomote automatically forwards common provider configuration to task workers, -including OpenRouter, Vercel AI Gateway, OpenAI, Azure OpenAI, Azure AI Foundry, -Anthropic, Google Gemini, -Moonshot, Kimi for Coding, MiniMax, Z.AI, OpenCode, Amazon Bedrock, xAI, and -GitHub Copilot keys. -Use `R_MODEL_ENV_KEYS` when a provider key uses a custom env var name: +Roomote automatically makes common provider configuration available to the +model runtime, including OpenRouter, Vercel AI Gateway, OpenAI, Azure OpenAI, +Azure AI Foundry, Anthropic, Google Gemini, Moonshot, Kimi for Coding, MiniMax, +Z.AI, OpenCode, Amazon Bedrock, xAI, and GitHub Copilot. For gateway-supported +providers, credentials stay on the control plane and model requests are proxied +instead of forwarding the credentials into task workers. Use `R_MODEL_ENV_KEYS` +when a provider key uses a custom env var name and must be forwarded: ```sh R_MODEL_ENV_KEYS=CUSTOM_PROVIDER_API_KEY diff --git a/apps/docs/providers/source-control/azure-devops.mdx b/apps/docs/providers/source-control/azure-devops.mdx index 941fb3ac..5bb98cef 100644 --- a/apps/docs/providers/source-control/azure-devops.mdx +++ b/apps/docs/providers/source-control/azure-devops.mdx @@ -18,7 +18,9 @@ Create a dedicated Azure DevOps bot or service-account user and give it access to the organization, projects, or repositories Roomote should use. Create a PAT for that identity with Code read/write permissions appropriate for cloning, branch creation, and commits. Enable Build read access for CI Failure Triage and -Work Items read access for work-item comment triggers. +Work Items read access for work-item comment triggers. Grant Service Hooks read +and manage access so Roomote can configure repository, pull-request, work-item, +and build event delivery. Save the organization and token in setup, deployment env vars, or local `.env.local`. Onboarding only asks for those two values by default: @@ -62,7 +64,7 @@ Service hook webhook secrets are generated automatically when Roomote configures service hooks. Advanced values remain editable later in Settings → Source Control. -#### Azure DevOps access +#### Required API permissions Azure DevOps does not use Microsoft Entra application permissions for service principals. Add the service principal to the Azure DevOps organization, assign diff --git a/apps/docs/self-hosting.mdx b/apps/docs/self-hosting.mdx index 20a1a9aa..9eef6754 100644 --- a/apps/docs/self-hosting.mdx +++ b/apps/docs/self-hosting.mdx @@ -11,8 +11,9 @@ Run the same single-tenant product on Roomote Cloud or infrastructure you control. Choose the fastest path for your team. In every deployment, you connect a -ChatGPT subscription or inference provider API key, plus the source control, -communications, sandbox, and other tools Roomote needs to do useful work. +ChatGPT subscription or inference provider API key, plus source control and a +sandbox provider. Connect communications providers and other tools when your +team needs them.
Deploy on Roomote Cloud