> ## Documentation Index > Fetch the complete documentation index at: https://docs.roomote.dev/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent 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. > 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. > 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. # Environments > Give Roomote the repositories, services, secrets, and guidance it needs to run and verify work. An environment is the workspace configuration Roomote uses when it runs a task. It can specify repositories to clone, services to start, environment variables, and guidance to follow. This is what turns a Roomote agent from a generic coding tool into something grounded in your actual product. For the full YAML schema behind an environment, including every field and how it relates to Dev Containers, see the [environment definition reference](/environments/definition). ## Start with one environment that can prove work The first environment matters more than the fifth. Start with one repository or repository set where Roomote can do real work and show enough evidence for your team to evaluate the result. A good first environment usually makes at least one of these possible: * run the main test command * start the app locally * open a preview * reproduce a bug with the services your team already uses * inspect the repositories that matter for a common support, product, or engineering workflow ## How the first environment is created Open **Settings > Environments > New** and choose repositories when the workspace needs source code. Add any setup guidance you already know, then select **Start Agent** so Roomote can define a reusable workspace configuration. If you already know the configuration you need, select **Enter YAML directly** instead. An environment can combine repositories from different source-control providers, such as GitHub and GitLab. Each provider must have working credentials in the deployment or the task cannot prepare the complete workspace. Repositories connected through GitHub must also belong to the same GitHub App installation. Repository full names must be unique within the environment, including across source-control connections. If the resulting environment needs changes, edit it from **Settings > Environments** and update the repositories, guidance, services, or YAML definition there. When an agent proposes creating or changing an environment, it first shows the concrete setup, expected maximum build time, and effect on running and future tasks. Creation or update waits for explicit approval of that exact proposal; administrator access alone is not consent, and a materially changed proposal must be approved again. ## Start from a brand-new repository You do not need an existing codebase to set up an environment. From **Settings > Environments > New**, choose **Create a new repository** to open github.com with the right owner pre-filled — either a brand-new repository or a fork of an existing one by URL. Once you create it on GitHub, it appears in the repository list automatically; if the GitHub App only has access to selected repositories, grant it access to the new repository first. An empty repository is fine. When you start setup against a repository with no commits, Roomote pushes a minimal initial commit (a README and a .gitignore) to the default branch and creates a basic environment. Building the actual project is then just your first task in that environment. ## What to include Add enough context for Roomote to start productively: * repositories and the default branch to use * setup commands, package manager expectations, and tool versions * services such as databases, caches, or local APIs * environment variables and secrets required for local development * named preview ports for web apps or APIs so Roomote can open a [Live Preview](/live-previews) * instructions that are specific to this workspace Environment changes apply to new tasks. Running tasks keep the workspace they already started with. For supported R/Bioconductor analyses, Roomote can also create a repository-free environment from an uploaded R script. The saved recipe pins the runtime image and package lock, is verified in a fresh workspace, and can be reused by later compatible scripts. Packages installed ad hoc during one task are not added to that recipe automatically. ## Edit an environment When you edit an existing environment, Roomote gives you four views of the same configuration: * **Editor** is the visual form for common environment settings. * **YAML** is the raw configuration for precise edits and advanced options. * **Diff** compares the saved configuration with your editable YAML draft. * **Preview** shows the saved structure in a more readable form before you use it for new tasks. The visual editor is organized around the parts Roomote needs to prepare a workspace: * **Basics** set the environment name, description, and initial URL that previews should open first. * **Services** add managed dependencies such as PostgreSQL, Redis, MySQL, MariaDB, ClickHouse, or the AWS CLI before repository setup commands run. * **Repositories** choose the repositories to clone, optional branches, repository-specific tool fallbacks, and setup commands for each repository. * **Docker Compose & Dockerfile** build and start an existing Docker Compose project or a single Dockerfile from one of the selected repositories. * **Environment Variables** provide values that tasks can read. * **Environment `.tool-versions`** writes a shared `.tool-versions` file at the workspace root. * **Exposed Ports** name the local web apps or APIs Roomote should preview. * **Agent Instructions** add environment-specific guidance that every task in this environment should receive. Less common options, such as custom MCP servers, are available in the YAML view. ## Write guidance Roomote can act on Good environment guidance is specific, durable, and tied to the workspace. Prefer guidance like: ```text theme={null} Use pnpm for this repository. Start Postgres before running the API. The web app runs on port 3000 and the API on port 3001. Run the dashboard test suite before changing task review flows. ``` Avoid vague guidance like: ```text theme={null} Be careful. Use best practices. Follow the normal process. ``` If a repository has a known trap, say it plainly. Short warnings such as "Preview will not load unless Redis is running" are more useful than general preferences. ## Choose setup commands Add commands that make the repository ready for useful work. Good setup commands are the same durable steps a teammate would run after cloning the repository, such as: * install dependencies, for example `pnpm install`, `npm ci`, `bundle install`, or `pip install -r requirements.txt` * generate local code or clients, for example `pnpm prisma generate` * run database migrations or seed scripts when local services need them * start long-running services, for example `pnpm dev`, with **Run in the background** enabled * write logs to a predictable file when a background process is important to debug 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. ## Use an existing Docker setup If the repository already defines its development dependencies in Docker, add 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. 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. 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 customer-controlled code, so review Compose files and Dockerfiles with the same care as repository setup scripts. ## Set tool versions at the right level Use **Repo tool fallbacks** for tools one cloned repository still needs when they are not already pinned in that repository's own `.tool-versions`. This is a good fit when one repository needs an extra fallback version without changing the repository itself. Use **Environment `.tool-versions`** for tools that should exist at the shared workspace root. This is most useful for workspace-level scripts, shared MCP servers, or as a broad fallback when a repository does not already pin a tool locally. When a repository already includes its own `.tool-versions`, keep that file as the source of truth. Environment-configured repository tool versions are fallback entries, not overrides, so checked-in repository pins still win. ## When to create multiple environments Use separate environments when work needs meaningfully different setup. Common examples: * one environment per product surface, such as web app, API, or background service * one environment for a monorepo service with heavy dependencies * one staging-style environment with extra credentials * one lightweight environment for code review, questions, and investigation ## Provision environments declaratively Self-hosted deployments managed as infrastructure as code can provision environments from declarative definitions at startup instead of creating them in the UI: * `ROOMOTE_ENVIRONMENTS_DIR` points at a mounted directory of definition files (`*.yaml`, `*.yml`, or `*.json`), one environment per file. * `ROOMOTE_ENVIRONMENTS_YAML` carries one or more inline YAML documents (separated by `---`) for platforms where mounting files is awkward. Definitions use exactly the same YAML format as the environment editor's YAML view, so they copy/paste between the UI and your files, and you can keep them in git next to the rest of your deployment configuration. The set is re-applied on every startup, keyed by environment name: missing environments are created, existing ones are updated, and identical re-applies are no-ops. The declarative definition wins — these environments stay editable and show a "Managed from file" badge, but UI edits are overwritten 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. See the [self-hosting guide](/self-hosting) for the compose mount pattern and operational details. ## Make verification possible Roomote works best when the environment lets it prove what changed. Include the commands and services needed to run tests, start the app, and open previews. For UI work, [configure Live Previews](/live-previews#prerequisites) so teammates can inspect the result without pulling the branch locally. ## Environment lifecycle Environment cards and detail pages derive their lifecycle from verification state: * **Configured** exists but is not verified for its current runtime configuration. * **Configuring** is a recipe environment whose packages are still being resolved by its verification task. * **Verifying** is a resolved environment with an active verification task. * **Ready** passed a verification task for its current configuration. * **Failed** is a resolution or verification error shown on the environment. Recipe environments are created on demand through the session's `ensure_environment` tool after one user confirmation; creation is administrator-only, while previewing and reusing an existing environment is open to members. An unresolved or unverified recipe environment is never routable for normal work. ## How to tell an environment is healthy An environment is in good shape when Roomote can do more than clone code: * setup finishes without manual intervention * the main commands it needs are discoverable and runnable * required services and secrets are available * previews or logs exist when the task should produce them * follow-up tasks can reuse the environment instead of rebuilding context from scratch ## Common issues * **Missing secrets or services** keep setup from getting to a runnable state. * **No preview ports** make UI work harder to verify. * **Too many repositories in one environment** can make the first setup slower and harder to debug. * **Overly broad guidance** forces Roomote to guess what actually matters for this workspace.