Skip to main content
An environment is the workspace configuration Roomote uses when it runs a task. It tells Roomote which repositories to clone, what services to start, what environment variables are available, and what guidance it should follow. This is what turns Roomote from a generic coding tool into something grounded in your actual product.

​
Start with one environment that can prove work

The first environment matters more than the fifth. Start with one repo or repo 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

During onboarding, you pick the repository or repositories for the first environment and add any setup guidance you already know. Roomote then starts an environment setup task that figures out how to run the app locally and prepare the workspace for future tasks. The setup task is meant to produce a working environment Roomote can reuse. If it cannot finish, onboarding keeps your repo selection and guidance so you can adjust the input and try again.

​
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, queues, 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
  • instructions that are specific to this workspace
  • links or notes for docs, logs, ticket systems, or other connected tools when relevant
Environment changes apply to new tasks. Running tasks keep the workspace they already started with.

​
Edit an environment

When you edit an existing environment, Roomote gives you three 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.
  • 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 AWS CLI before repository setup commands run.
  • Repositories choose the repos to clone, optional branches, repo-specific tool fallbacks, and setup commands for each repo.
  • Environment Variables provide values that tasks can read. Values can be literal or reference encrypted organization variables.
  • 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.
  • Advanced summarizes less common settings that are still present in the YAML, such as custom MCP servers, skills, or OIDC tokens.

​
Write guidance Roomote can act on

Good environment guidance is specific, durable, and tied to the workspace. Prefer guidance like: 
Use pnpm for this repo.
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: 
Be careful.
Use best practices.
Follow the normal process.
If a repo 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 repo, 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.

​
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 repo’s own .tool-versions. This is a good fit when one repo needs an extra fallback version without changing the repo 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 repo does not already pin a tool locally. When a repo already includes its own .tool-versions, keep that file as the source of truth. Roomote now treats environment-configured repo tool versions as fallback entries, not overrides, so checked-in repo 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 worker
  • 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

​
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 preview ports so teammates can inspect the result without pulling the branch locally.

​
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

​
Agent guidance

Environment guidance should be concrete and durable. Prefer instructions like “run pnpm test --filter @acme/web before changing web routes” over broad preferences that apply to every repository. Use organization-level guidance for cross-team rules, and environment guidance for workspace-specific rules.

​
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 repos 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.