Environment definition

An environment definition is the YAML document that describes a Roomote environment: repositories to clone, services to start, tools and environment variables to provide, ports to preview, and guidance every task in that environment should receive. The visual editor and the onboarding setup agent both produce this same YAML. This page documents the format directly so you can read, review, and write a definition yourself, or point a local coding agent at these docs and have it generate a valid definition for you.

What the definition is for

When a Roomote agent starts a task, the sandbox provider gives it a clean sandbox. The environment definition is what turns that empty sandbox into a workspace grounded in your product. It is applied in a predictable order:

requested services (databases, caches) start while repositories are prepared
shared workspace tool fallbacks are installed after repositories are ready
configured Docker projects are built and started from cloned repositories
each repository’s setup commands run, in order
named ports become live previews, and agent instructions are attached to every task

The definition is declarative and reproducible: the same YAML produces the same workspace shape for every task, and it is easy to review in a pull request or regenerate from scratch.

Relationship to Dev Containers

If you have used Dev Containers, the environment definition will feel familiar. Both describe a development workspace as a version-controllable, declarative file so that anyone (or any agent) gets the same setup. The concepts map closely:

Concept	Dev Container (`devcontainer.json`)	Roomote environment definition
Base machine	`image` / `build`	Provided by the sandbox provider worker image, not set here
Extra tooling	`features`	`services` and `tool_versions`
Setup steps	`onCreateCommand` / `postCreateCommand`	Repository `commands`
Forwarded ports	`forwardPorts` / `portsAttributes`	`ports`
Workspace env vars	`containerEnv` / `remoteEnv`	`env` (and per-command `env`)
Tool customizations	`customizations`	`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 a Dev Container, treat it as a reference for which tools, services, and commands matter, then express those in the environment definition described below. For the Dev Container spec itself, see the Dev Container specification and the metadata reference rather than duplicating them here.

A complete example

The definition below is a self-contained example that uses most of the available fields. Every field is explained in the reference sections that follow.

name: Acme Web
description: Web app and API for the Acme product.
initialUrl: http://127.0.0.1:3000

# Tools installed at the shared workspace root, as a broad fallback.
tool_versions:
  node: 22.14.0
  pnpm: 9.12.0

# Workspace-level environment variables available to every task.
env:
  NODE_ENV: development
  LOG_LEVEL: debug

# Managed services started before repository setup runs.
services:
  - postgres16
  - name: redis7
    port: 6380

repositories:
  - repository: acme/web
    branch: main
    # Per-repo tool fallbacks, used only when the repo does not pin them itself.
    tool_versions:
      python: 3.12.1
    commands:
      - name: Install dependencies
        run: pnpm install
      - name: Run migrations
        run: pnpm db:migrate
        timeout: 300
      - name: Start dev server
        run: pnpm dev
        detached: true
        logfile: /tmp/web-dev.log
      - name: Optional cache warm
        run: pnpm cache:warm
        continue_on_error: true

  - repository: acme/api
    commands:
      - name: Install dependencies
        run: pnpm install

# Start an existing Compose project after acme/web is cloned.
docker_projects:
  - type: compose
    name: app
    repository: acme/web
    files:
      - compose.yaml
    services:
      - web
    ports:
      - named_port: WEB
        service: web
        container_port: 3000

# Named ports exposed as human-facing previews.
ports:
  - name: WEB
    port: 3000
    initial_path: /
    primary: true
  - name: API
    port: 3001

# Environment-specific guidance attached to every task.
agentInstructions: |
  This is a monorepo. The web app is in acme/web and the API is in acme/api.
  Start Postgres and Redis before running the API.
  Run `pnpm test` in acme/web before finishing UI changes.

Top-level fields

Field	Type	Required	Notes
`name`	string	yes	Environment name, 1–100 characters.
`description`	string	no	Short summary, up to 500 characters.
`repositories`	list	no	Repositories to clone. See Repositories.
`initialUrl`	string	no	Absolute URL or `about:blank` that the preview surface opens first.
`agentInstructions`	string	no	Guidance attached to every task, up to 10,000 characters.
`tool_versions`	map	no	Tools installed at the shared workspace root via mise.
`env`	map	no	Workspace environment variables available to every task.
`services`	list	no	Managed services to start. See Services.
`docker_projects`	list	no	Existing Compose or Dockerfile projects to build and start. See Docker projects.
`environment_recipe`	map	no	A resolved on-demand runtime created by Roomote through `ensure_environment`. Unresolved recipes are an internal provisioning state and cannot be saved directly. See Environment recipes.
`ports`	list	no	Named preview ports. See Ports.
`oidc`	map	no	Sandbox OIDC targets. See OIDC.
`mcpServers`	map	no	Custom MCP servers for this environment. See MCP servers.
`skills`	map	no	Installable skills by `owner/repo`. See Skills.
`manualSkills`	list	no	Inline skills defined in the environment. See Skills.
`auth_bypass_header`	boolean or string	no	Header-based auth bypass control for exposed authenticated previews. A fixed string secret must be at least 8 characters.
`auth_bypass_header_name`	string	no	Custom bypass header name. Defaults to `x-bypass-roomote-auth`.

Basics

name is the only required top-level scalar. description and initialUrl are optional but recommended: initialUrl is the URL the shared preview surface opens first, so point it at the app entry a reviewer would expect, for example http://127.0.0.1:3000. Use about:blank when there is no default page.

Repositories

repositories is optional. Each listed repository is cloned onto the shared workspace.

Field	Type	Required	Notes
`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.

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. GitHub repositories in one environment must belong to the same GitHub App installation.

Environment recipes

Environment recipes give a Roomote task a reproducible runtime without a repository Dockerfile or lockfile. A recipe has a normalized request and request_fingerprint; once the trusted image-provided worker resolves it, a complete pinned resolution with its own resolution_fingerprint is persisted. The first supported type is r-bioconductor. Requested direct packages are dynamically resolved from the official CRAN and Bioconductor repositories inside a pinned image (R 4.5.2 / Bioconductor 3.21 on a digest-pinned bioconductor/bioconductor_docker image). GitHub remotes, local packages, private registries, and dynamically computed package names are out of scope: they fail with an actionable error rather than silently installing something unexpected. Recipe environments are created through the session’s ensure_environment tool after one user confirmation; only deployment administrators can create them, and read-only preview and reuse are available to members. The resolved portion of a recipe is system-managed — direct admin YAML/API edits invalidate verification like any other runtime-affecting change — while the environment lifecycle is derived from recipe and verification state:

Configuring: a request with an active verification task but no persisted resolution yet.
Verifying: a resolved recipe with an active verification task.
Ready: successfully verified.
Failed: resolution or verification error.
Configured: an ordinary non-recipe environment.

An unresolved or unverified recipe environment is never routable for normal work.

Commands

Each entry in a repository’s commands list runs in order after the repository is cloned. Commands are the durable setup steps a teammate would run after cloning: installing dependencies, generating code, running migrations, and starting long-running services.

Field	Type	Required	Notes
`name`	string	yes	Human-readable label for the step.
`run`	string	yes	The shell command to run.
`env`	map	no	Command-specific environment variables, merged over workspace `env`.
`working_dir`	string	no	Directory to run the command in.
`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`.
`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`.

Guidance:

keep commands focused on setup, not final verification. Put “run the tests 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.

Services

services starts managed dependencies before repository setup runs. Each entry is either a service name string or an object with a name and a custom port. Supported services:

Service	Default port
`redis6`, `redis7`	6379
`postgres15`, `postgres16`, `postgres17`	5432
`mysql8`, `mariadb10`	3306
`clickhouse`	9000
`aws`	CLI tool, no port

services:
  - postgres16 # default port 5432
  - name: redis7
    port: 6380 # custom port

A service name cannot collide with a port name in the same environment.

Docker projects

docker_projects runs Docker Compose or Dockerfile definitions already owned by a configured repository. Roomote validates the Compose model, builds images, starts services through Docker Compose, and treats startup as required unless required: false is set.

Configure a project

In Settings > Environments, create or edit an environment, then:

Add the repository that contains the Compose file or Dockerfile.
Open Docker Compose & Dockerfile and select Add Docker project.
Choose Docker Compose or Dockerfile, select the repository, and set Working directory relative to the repository. Compose file paths and Dockerfile build paths are relative to that working directory. For Compose, you can also select profiles or limit startup to specific services.
Add any human-facing ports under Exposed Ports, then map each named port to its container port. A Compose mapping must also name the service that owns the port.
Leave Fail environment startup if this project cannot start enabled for anything the workspace requires.

The YAML view represents the same configuration and supports the full schema below. Roomote validates the definition when you save it.

Use images from Compose

For an existing image, put a normal Compose image: reference in a Compose file in the selected repository. docker_projects does not have an image field. Use type: dockerfile instead when Roomote should build an image from a repository Dockerfile. Image references follow Docker Compose conventions, so Docker Hub names such as nginx:1.27-alpine and fully qualified registry names are valid. Pin a specific tag or digest when reproducibility matters. The sandbox must be able to pull the image without an interactive login: the environment schema has no registry credential field, and Roomote does not run docker login for a project. Do not put registry credentials in the image URL, Compose file, or environment YAML. For example, commit this compose.yaml to acme/web:

services:
  web:
    image: nginx:1.27-alpine
    healthcheck:
      test: [CMD, wget, --spider, http://127.0.0.1/]
      interval: 2s
      timeout: 2s
      retries: 15

Then configure Roomote to start it and publish container port 80 as the named WEB preview:

name: Acme web container
repositories:
  - repository: acme/web

docker_projects:
  - type: compose
    name: web
    repository: acme/web
    files:
      - compose.yaml
    services:
      - web
    ports:
      - named_port: WEB
        service: web
        container_port: 80

ports:
  - name: WEB
    port: 8080
    primary: true

The optional Compose services list selects which services Roomote starts; it is different from the top-level services field, which provisions Roomote-managed dependencies such as PostgreSQL or Redis. Do not configure the same dependency both ways.

Startup and readiness

Roomote automatically builds and starts configured Docker projects after their repositories are prepared and before repository setup commands run. Do not add docker compose up as a setup command or tell an agent to start Docker again. Agents receive setup status and Docker-project log locations so they can observe builds and health checks without creating duplicate containers. On sandbox providers that support Docker health checks, Compose waits until the selected services are running or healthy. Add a Compose healthcheck when “container started” is not enough to show that a dependency is ready. Blaxel does not support Docker health checks, so Roomote continues after Compose starts the services there. The startup timeout defaults to 600 seconds and can be set to at most 3600 seconds. A required project fails environment setup when it cannot become ready; an optional project records a warning and setup continues. If a task begins while setup is still running, the agent should wait for the top-level state in .roomote/setup-status.json to settle and follow the Docker project log path included in its environment instructions. An empty docker compose ls during that window can simply mean the image is still being built or pulled. Common fields:

Field	Type	Required	Notes
`type`	`compose` or `dockerfile`	yes	Selects the source format.
`name`	string	yes	Unique project name.
`repository`	string	yes	Must exactly match a repository in this environment.
`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`.
`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. Optional profiles enables Compose profiles, and optional services limits startup to those services. Each port mapping requires named_port, service, and container_port.

docker_projects:
  - type: compose
    name: development
    repository: acme/web
    working_dir: infra/local
    files: [compose.yaml, compose.override.yaml]
    profiles: [development]
    ports:
      - named_port: WEB
        service: web
        container_port: 3000

For type: dockerfile, Roomote generates a one-service Compose project. context defaults to ., dockerfile defaults to Dockerfile, and target, build_args, and command are optional. Dockerfile port mappings omit service because the generated service is implicit.

docker_projects:
  - type: dockerfile
    name: web
    repository: acme/web
    context: .
    dockerfile: Dockerfile
    target: development
    ports:
      - named_port: WEB
        container_port: 3000

All paths must be relative and stay inside the selected repository. Docker projects are supported by all sandbox providers. Modal runs them in its beta VM sandbox runtime.

Ports

ports declares the human-facing application URLs Roomote should expose as live previews. Inside the sandbox, each named port gets a shareable ROOMOTE_<NAME>_PREVIEW_URL, protected by preview authentication unless unauthenticated is enabled. ROOMOTE_<NAME>_HOST points to that preview URL for proxied ports and to the direct machine host for unproxied ports. Agents and browser tooling should use ROOMOTE_<NAME>_PREVIEW_URL to test the preview entrypoint.

Field	Type	Required	Notes
`name`	string	yes	Starts with a letter; letters, numbers, and underscores only. Case-insensitive and unique. `SANDBOX_SERVER` and `EDITOR` are reserved.
`port`	number	yes	The listening port, 1024–65535.
`primary`	boolean	no	Marks the main preview surface. At most one port may be primary.
`initial_path`	string	no	Path the preview opens first. Must start with `/`.
`proxied`	boolean	no	Whether the port is served through the preview proxy. Defaults to proxied.
`unauthenticated`	boolean	no	Allow access without the normal preview auth.
`auth_bypass_paths`	list	no	Up to 20 paths (each starting with `/`) that skip preview auth.
`subdomain`	string	no	DNS-safe subdomain prefix for the preview host.
`wildcard_prefix`	boolean	no	Serve wildcard subdomains under the port.

Limits: at most 10 proxied ports and at most 2 non-proxied ports per environment.

ports:
  - name: WEB
    port: 3000
    initial_path: /dashboard
    primary: true
  - name: API
    port: 3001

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 that configure Roomote itself. Secrets are typically added through the editor rather than committed to a definition you share. Tool versions can be set at two levels:

tool_versions at the top level installs tools at the shared workspace root via mise. Use this for workspace-level scripts, shared MCP servers, or as a broad fallback.
tool_versions on a repository provides fallbacks for a single repository.

In both cases, a repository’s own checked-in .tool-versions stays authoritative. Environment-configured versions are fallbacks that fill in missing tools; they do not override repository-owned pins.

tool_versions:
  node: 22.14.0
  python: 3.12.1

Agent instructions

agentInstructions is guidance delivered to every task in the environment. Good guidance is specific, durable, and tied to the workspace:

agentInstructions: |
  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 instructions like “be careful” or “use best practices.” If a repository has a known trap, state it plainly.

Routing rules

Admins can configure natural-language routing rules from Settings → Environments. Each rule maps a description, such as “Messages sent in the hospital-bugs Slack channel,” to an environment or the broad All repositories workspace. An All repositories sandbox does not clone every repository up front; it starts with a REPOSITORIES.md index of the active repositories and the agent checks out the ones the task needs. Environment and repository-scoped sandboxes expose the same index after preparing their initial repositories. The selected workspace controls initial checkout and tooling; checking out another authorized repository does not run another environment’s setup commands or provision its services. A rule can also recommend a coding model for work that Roomote delegates. Rules are guidance rather than exact string matchers. An environment explicitly named in a request takes precedence, and a specific rule takes precedence over a catch-all default. Roomote evaluates the saved rules when it chooses an environment or model for a delegated task; they do not override a model or environment the user explicitly requested. Rules that point to a deleted environment are ignored until an admin updates or removes them.

MCP servers

mcpServers adds environment-specific MCP servers that are merged with built-in tools when a task starts. Each entry is either a streamable HTTP server (url, optional headers) or a stdio server (command, optional args and env).

mcpServers:
  linear:
    url: https://mcp.linear.app/mcp
  local-tool:
    command: my-mcp-server
    args:
      - --stdio
    env:
      MY_TOKEN: value

Skills

skills installs published skills by source, keyed by owner/repo. The value is either all or a list of specific skill names.

skills:
  dbt-labs/dbt-agent-skills: all
  anthropics/skills:
    - frontend-design
  vercel-labs/agent-skills:
    - web-design-guidelines

manualSkills defines inline skills directly in the environment. Each entry needs a unique name, a description, and content with the skill instructions.

manualSkills:
  - name: acme-conventions
    description: Adds Acme-specific coding conventions.
    content: |
      # Acme Conventions

      Always use the shared logger from @acme/log.

OIDC

oidc declares sandbox OIDC targets. Roomote mints the tokens, writes them into the sandbox filesystem, and refreshes them while the sandbox is active. Use aws for an AWS role and custom for additional audiences.

oidc:
  aws:
    role_arn: arn:aws:iam::123456789012:role/example
    region: us-east-1
  custom:
    - audience: my-audience
      token_file: /home/roomote/.roomote/oidc/custom/token

Each token_file must be an absolute path and must be unique across targets.

Write a definition with a coding agent

Because this page fully describes the schema, you can have a local coding agent generate a definition as an alternative to the in-app setup agent. A reliable approach:

give the agent this page as context, along with the repository you want to set up
ask it to infer the tools, services, setup commands, and preview ports from the repository’s own README, package manifests, lockfiles, CI config, and any existing devcontainer.json
have it emit a single YAML document that matches the schema above, starting from name and repositories
paste the result into the YAML view when you create or edit an environment in Settings > Environments

The editor validates the definition when you save, so schema mistakes are caught before the environment is used for a task.

Validate and iterate

The visual Editor, YAML, Diff, and Preview views in the environment editor all operate on this same document, so you can switch between hand-written YAML and the form freely. Diff keeps the saved configuration read-only on the left while you edit the YAML draft on the right. Roomote validates the definition on save; fix any reported errors before the environment runs a task. After saving, the surest test is to run a real task. A healthy environment finishes setup without manual intervention, exposes the previews or logs a task needs, and can be reused by follow-up tasks. See Environments for the broader workflow and common failure modes.

Getting started

Using Roomote

Automating Work

Configuring Providers

Integrations

Configuring Roomote

Analytics

Development

What the definition is for

Relationship to Dev Containers

A complete example

Top-level fields

Basics

Repositories

Environment recipes

Commands

Services

Docker projects

Configure a project

Use images from Compose

Startup and readiness

Ports

Environment variables and tool versions

Agent instructions

Routing rules

MCP servers

Skills

OIDC

Write a definition with a coding agent

Validate and iterate

​What the definition is for

​Relationship to Dev Containers

​A complete example

​Top-level fields

​Basics

​Repositories

​Environment recipes

​Commands

​Services

​Docker projects

​Configure a project

​Use images from Compose

​Startup and readiness

​Ports

​Environment variables and tool versions

​Agent instructions

​Routing rules

​MCP servers

​Skills

​OIDC

​Write a definition with a coding agent

​Validate and iterate

What the definition is for

Relationship to Dev Containers

A complete example

Top-level fields

Basics

Repositories

Environment recipes

Commands

Services

Docker projects

Configure a project

Use images from Compose

Startup and readiness

Ports

Environment variables and tool versions

Agent instructions

Routing rules

MCP servers

Skills

OIDC

Write a definition with a coding agent

Validate and iterate