Skip to main content
Configure what gets injected into workspaces from Environments in the app sidebar. Open an environment to edit its repositories, instructions, variables, setup scripts, tools, skills, and files on one page.
Use the API, MCP server, or CLI to manage environments, variables, files, skills, MCPs, plugins, hooks, and warm pools.

Environments

Every environment works the same way: a fork inherits its parent’s setup, and an environment without a parent starts empty. To share setup across environments, fork them from a common parent. Every organization has a default environment, which only routes Scout and untagged Slack and Linear requests: change it with Make default in an environment’s ⋯ menu, which marks it Default in the list. Deleting or archiving the default makes the most-used remaining team environment the default. Add any number of named team and personal environments. Each environment has a list of repositories its workspaces clone (possibly none), each into ~/workspaces/<repo-name>. Repositories that share a name, like groupA/app and groupB/app, clone into their full path instead: ~/workspaces/groupA-app and ~/workspaces/groupB-app. Onboarding creates one team environment named after your organization with every repository you picked, and makes it the default. Adding a repository never creates an environment; add it to an environment instead. An environment can combine repositories from different GitHub organizations, personal accounts, and GitLab. Repository checkout names must be unique (for example, company/api and personal/web). With PR user attribution, your connected GitHub account must be able to read every repository, and needs write access to push changes. Startup and credential refresh identify repositories your account cannot read so you can fix user access, app installation permissions, or organization SSO. A combined environment receives only its own configuration; it does not inherit the separate frontend and backend environments. Move their required variables, files, and hooks into the combined environment, resolving any duplicate keys or paths. Every variable, file, skill, MCP, and environment plugin install belongs to a single environment. When a workspace runs in a fork, it receives each parent merged underneath it. Values in the selected environment win on conflict. Personal environments are only visible to their owner. Create one from scratch or inherit from a team environment, then add private variables/files/MCPs such as personal service tokens without exposing them to the rest of the team. At runtime, a plain personal environment receives only its own values. A personal environment created from a team environment is a fork.

Forks

A fork is “forked from” one parent and stays linked to it. It receives each ancestor, starting with the root, then its own values, and stores only what it changes:
  • Adding a variable, file path, MCP name, skill, or registry URL it inherits overrides it. Deleting an inherited item, including a plugin or Doppler/Infisical connection, excludes it. Reset to inherited removes either.
  • Locked variables can’t be overridden or excluded below the environment that locked them. A lock applies to every environment below it.
  • System prompts, start hooks, and warm hooks are additive. The repository binding, memory, GPU sandboxes, and mobile testing settings are inherited until the fork sets its own. Each fork has its own warm pool.
  • Team environments fork into team or personal forks; your own personal environments fork into personal ones. Plain environments have no parent; to build on another environment, pick it as the Source or fork it. Other people’s personal environments can’t be forked. Forks nest up to 3 levels below a root environment, and team forks count toward your environment limit.
  • Detach copies everything inherited into the fork and removes the link. Connected plugin accounts and MCP OAuth sign-ins can’t be copied, so reconnect them. Deleting an environment detaches its forks first, including other people’s personal forks.
In the app, Fork in the environment header creates a team fork of a team environment, or a personal fork of your personal environment. In every section, inherited items are marked Overridden, Excluded, or Locked; Exclude drops one from this environment, Include again brings it back, and Reset drops an override. The API covers the same (fork, detach, get effective environment, exclude inherited item, reset to inherited). Environments with no workspace started in 30 days are listed behind a dismissible banner on the Organization tab; Review lets you archive them (or Archive all). Archived environments are hidden from lists and pickers, drop their warm pool (its snapshots are deleted 3 days after archiving), and still work for existing references; Show archived restores them. Nothing is merged or deleted automatically. In the app, the Organization tab shows team environments, with forks nested under the environment they came from, while Your Environments shows personal environments. The overview shows each environment’s repository scope, status, and last update. Create Environment creates in the active tab. The new environment popover has a Source picker for Plain vs forking an existing team environment. Open an environment to see its status pinned at the top and its settings in sections: General (repositories, instructions, memory, GPU sandboxes, mobile testing, workspace identity, delete), Environment Variables, Setup, Tools, Devices, Skills & files, and History. Each block saves on its own. Edit the name and description inline at the top of the page, and select the icon next to the name to pick a different one. A section in the left rail shows a spinner while its changes are applying and a dot when it caused a failure. Fork creates an environment that inherits this one, a team fork from a team environment or a personal fork from a personal one; a fork shows Fork of its source next to its name. In Environment Variables, paste a whole .env into a Key field to add every line, or use Import .env. Keys that look like secrets are marked Sensitive: their values are never shown again after saving, and a sensitive variable can’t be made readable later. Raw editor edits this environment’s variables as KEY=VALUE lines. In a fork, variables shared from the source are listed separately: override or reset them, unless the source locked them.

Status

A status line under the environment name says what a workspace started now gets. An environment with no workspace started in 7 days keeps no warm workspaces, but its edits still rebuild its setup. After 30 days without one, it also drops its setup snapshot, and edits show Ready until it’s needed again. Selecting it on Home, starting a workspace in it, or a scheduled automation that’s about to run rebuilds it. Instructions, the start hook, MCPs, and most variables apply as soon as you save. Rows that are part of a pending update are marked applying. When an environment needs attention, the page shows what it tried to apply, the likely cause read from the log, and the end of the log. From there:
  • Fix with agent starts an agent that begins from the failing log and script, and proposes a fix for you to review.
  • Edit warm hook or Try again after fixing the cause elsewhere, such as a missing variable.
  • Undo these changes puts the setup back to the one that’s live.

Logs

Setup lists the active warm and start steps in execution order, with their source and last run. Inherited steps identify their parent environment. Repository steps are read-only and link to their config file. App hooks share a result for the whole app-hook chain; repository hooks show their own results. View run log opens the full run log. A workspace whose start hook failed shows a banner that opens its log.

Setup sources

Choose which hooks run from Setup on each environment: The selected environment’s mode controls the whole hook chain, including parent hooks. Changing the mode keeps your saved scripts. It only controls which sources run; other repository configuration still applies.

History

History lists changes that reached new workspaces. Select Restore to bring back its warm hook, repositories, variables, files, and skills. The workspace image built from them is reused when it is still available; otherwise the setup is rebuilt. The last 10 can be restored.

Repository binding

In General, use Add repository to search connected repositories plus, for organization admins, everything the GitHub App or GitLab connection can access; picking one adds it. Use Grant access on GitHub when a repository is missing. Select × on a repository to remove it. In a fork, adding or removing one gives it its own list; Reset to inherited goes back to its source’s. Shared automations cannot target personal environments. Personal automations can use personal environments owned by the same user. Personal environments do not enable a warm pool on create. Each environment can also carry an optional system prompt that is injected into the agent’s instructions when a workspace runs in that environment. Use it to pin a persona or domain focus (e.g., “You are a debugging specialist focused on observability.”) that should travel with every workspace bound to that environment. A fork’s own system prompt is appended after its parent’s. A personal environment can also add personal preferences inline from the environment overview. These instructions are appended after the inherited prompt and passed to the agent as the workspace owner’s preferences (e.g., how you like information presented or code written). Environment instructions win on conflict.

Environment access

Admins grant Read or Write on all environments, or on specific ones, from Roles & access on the Members page. Read lets a member inspect an environment and start workspaces on it; Write also lets them change or delete it. Personal environments are visible only to their owner. A fork is capped by its parents: members need Read on every ancestor to see it, on top of the fork’s own grants. Agents in a workspace get the workspace owner’s access; workspaces without an owner, such as shared automation runs, act for the whole organization. Forking requires Read on the parent. A team fork starts with its parent’s access grants.

Variables

Key-value environment variables injected into workspaces at boot.
  • Belong to a specific environment
  • Values are encrypted at rest
  • Paste .env-formatted blocks or use Upload .env to batch add. Quoted multiline values remain one variable; review the imported rows, then select Save all to persist them together
  • Secrets can also be synced from Infisical or Doppler. Manual variables take priority over integration secrets
  • Variables are overrideable by default. Admins can lock team variables so forks can’t override them
  • Forks show inherited variables as rows, with inline editing for keys that aren’t locked

When an agent needs a variable

Agents ask with replicas environment vars request <KEY>.... A form appears above the chat composer on web and mobile: paste a value per key, or paste a whole .env to fill every matching key at once. Values are saved to This workspace only by default. To give new workspaces the values too, choose Save to one or more environments you can edit. The agent loads the values into its running workspace and continues; values never appear in the chat. When you work with an agent from Slack or Linear, it sends you a link to the form instead.

Workspace identity

Workspace identity (OIDC) lets a workspace mint a short-lived signed token for any service it calls. The issuer and key URLs your services verify against are shown under General.

Files

Configuration files placed inside workspaces.
  • Place files at ~/... (home directory) or ~/workspaces/... (alongside cloned repos)
  • Belong to a specific environment
  • Max file size: 64 KB
  • Contents are encrypted at rest

Skills

Install skills from the skills.sh directory into your workspaces.
  • Belong to a specific environment
  • Search by name or slug to find available skills
  • Enable or disable per environment
Skills can also be committed directly to a repo under .claude/skills/, .codex/skills/, or .agents/skills/. Each one is linked into ~/.claude/skills and ~/.agents/skills, so every agent loads it; a skill in more than one of these folders is linked once. See per-repo agent config. The Skills tab lists every skill in one place, each marked with where it comes from: the built-in Replicas Agent skill, the skills, agents, commands, and prompts committed to the environment’s repositories under .claude/, .codex/, and .agents/ (read-only), skill registries, skills.sh skills, and skills inherited from parent environments. Add skills searches skills.sh or adds a GitHub repository as a registry.

Skill registries

Add GitHub repository URLs as skill registries to automatically install skills from external repos into every workspace at startup.
  • Belong to a specific environment
  • Discovered patterns: .claude/skills/, .codex/skills/, .agents/skills/, top-level skills/*/SKILL.md, root-level SKILL.md, and .claude-plugin/plugin.json manifests
  • Skills are symlinked into ~/.claude/skills, ~/.codex/skills, and ~/.agents/skills at provisioning time for Claude, Codex, Muse, Pi, and Opencode-compatible runtimes, and into ~/.gemini/config/skills for Gemini
  • Pre-warmed workspaces refresh registries from GitHub and reinstall discovered skills when claimed, so registry changes are picked up before use
  • Uses your organization’s GitHub credentials when available; falls back to anonymous access for public repos
  • Add one with Add skills → GitHub repository on the Skills tab
To load skills from a private repository without sharing it with your team, add it to one of your personal environments. Replicas reads it with your personal GitHub connection, and the Replicas GitHub App must be installed on the repository’s owner with access to it. Only you can see its skills, they install only in your workspaces, and your GitHub token never enters the workspace. If your access is removed, the registry shows the error on the Skills tab and workspaces start without it.

Default skills

Replicas auto-installs the replicas-agent skill (highly recommended) into every workspace so agents have a consistent baseline for Replicas-managed integrations. It’s the Replicas Agent row on any environment’s Skills tab; expand it to toggle abilities. Forks inherit their parent’s setting until they change it; Reset goes back to inheriting. Most abilities can be turned off individually if your org already has a dedicated skill or workflow for it:
  • computer: drive the workspace Linux desktop (click, type, screenshot, record) and stream a live H.264/Opus viewer
  • docker: start the daemon, build / run containers, drive docker compose
  • github: pre-authenticated gh CLI for PRs, issues, releases, and GraphQL
  • gitlab: pre-configured git credentials for GitLab, used to push, pull, and open merge requests via git push options
  • linear: fetch issues, post comments, update state via the Linear API
  • media: share screenshots, recordings, generated images, and audio clips
  • plugins: call installed marketplace tools from TypeScript (see Plugins)
  • previews: expose locally running services on public preview URLs
  • replicas: use the in-workspace replicas CLI to manage automations / envs / files
  • sentry: read projects and issues via the Replicas gateway (see Sentry)
  • slack: send messages, read threads, search conversations, transfer files
Disabling an ability removes it from the installed skill on disk and from the system-prompt guidance, so agents never learn about an integration the org has opted out of. Toggling these settings invalidates warm pools so the next workspace reprovisions with the new skill set.

MCPs

Configure MCP servers that workspaces can connect to.
  • Belong to a specific environment
  • Supported transports: stdio, http, sse. Claude and Opencode sessions load all three transports. Codex sessions load stdio and streamable http MCPs; sse is Claude/Opencode-only.
  • Codex auto-approves tools from provisioned MCP servers inside disposable workspace VMs.
  • Secrets in the config (env vars for stdio, headers for http and sse) are encrypted at rest
  • Distinct from the hosted Replicas MCP server, which exposes Replicas itself to your tooling
  • An http or sse MCP can authenticate with a workspace identity token instead of a stored header by setting config.auth to { "type": "workspace_identity", "audience": "<audience the server verifies>" }
  • Click Add MCP or a Suggested server. For a remote server, enter its URL, a name (defaults to the server’s domain), and an optional token, sent as Authorization: Bearer <token>. Replicas checks the token when you save, so a server that rejects it shows an error instead of failing later in workspaces. Switch to Command to run a local stdio server. Advanced holds SSE, extra headers, and workspace identity.
  • Leave the token empty and Replicas signs in with OAuth if the server asks, as Notion, Attio, and Kondo do (config.auth set to { "type": "oauth" }, http only). The MCP is saved once the sign-in succeeds. Replicas registers itself with the server (with a Client ID Metadata Document when the server supports one, otherwise dynamic client registration) and refreshes tokens, and every workspace in the environment uses that account. If the server rejects Replicas or a saved sign-in stops working, the MCP shows why and offers Reconnect. Once it’s connected, headers you add under Advanced, like Datadog’s X-Datadog-MCP-Toolsets, are sent along with the sign-in. Add the MCP to a personal environment to keep the account private.

MCP servers or plugins?

Both connect an app to the agent. Use one or the other for each app, not both, or the agent gets two sets of tools for the same app. Notion, Jira, Confluence, Datadog, and PagerDuty are offered as both. For these, add the MCP server. The exception is read-only access to Jira or Confluence, which the plugins offer. For any other app, use whichever one offers it.

Plugins

Install plugins for the workspaces that use this environment.
  • Install shared plugins on a parent environment; its forks get them through their fork chain
  • Anyone with Write can manage plugins; personal environments remain owner-only
  • A workspace resolves each plugin from the most specific environment in its chain that has one installed

Attaching an environment to an automation

Each automation runs in exactly one environment, picked from the Environment dropdown in the automation editor. The environment supplies its configuration (including its parents’, if it is a fork), plus its repositories. Pick the environment whose vars / MCPs / skills and optional repository binding the automation should run with.

Slack and Linear intake

Slack and Linear intake also pick an environment for the workspace they create. The env’s repositories are cloned. Users can set a personal default under Personal → Preferences, and org admins can set a team default under Organization → Settings → Preferences.

Warm Hooks

Warm hooks are available on every plan.
Warm hooks run setup scripts ahead of time so workspaces provision instantly from a pre-warmed pool instead of waiting for dependency installs and builds on every boot.

Levels

Warm hooks from the enabled setup sources layer in a fixed order. Each level is optional. Level 1 is configured in Environments; a fork shows its ancestors’ hooks read-only above its own. Level 2 is committed alongside the code. Save an empty environment script to clear the active warm hook.

Execution order

During pre-warming, the engine runs the hooks in this order, in the same workspace:
  1. Environment warm hooks, starting with the root, then each ancestor, then the selected environment, each in its own subshell
  2. Repository warm hook(s), one per cloned repo, alphabetical by repo name
Repositories are cloned to ~/workspaces/<repo> before any hook runs. Environment warm hooks run in ~/workspaces, and each repository warm hook runs in its repository’s folder. Each step must exit 0 before the next runs; a failure stops the chain and marks the warmup failed. Within a single step, commands run sequentially and stop on the first non-zero exit. The repository step is itself a loop, so a failure in the alphabetically first repo aborts the remaining repos. Once pre-warming succeeds, the snapshot is added to the pool and the workspace’s startHook (from replicas.json / replicas.yaml) runs at assignment time.

When to use each level

  • Parent environment — setup that every fork needs (auth bootstrapping, shared CLI installs).
  • Environment — setup specific to one environment’s repo, vars, or persona (e.g., a staging-only build flag).
  • Repository — setup that belongs with the code: dependency installs, codegen, asset builds. Commit it so every environment that clones the repo gets the same prep for free.

Repository-level config

Add a warmHook field to your replicas.json or replicas.yaml:
timeout is per command in milliseconds. warmHook defaults to 60 minutes (capped at 120 minutes) since warm-pool builds often include heavy installs and image pulls; startHook defaults to 5 minutes (capped at 15 minutes). See Repository Configuration for the full file schema.

Warm pools

Warm pools keep pre-warmed workspaces ready per environment.
  • Warm pools are enabled by default on new team environments. Personal environments start with warm pools off.
  • Pool size follows each environment’s recent demand: deeper at the hours it usually gets bursts of new workspaces, and empty until it starts a second workspace within 7 days. New workspaces start from the environment’s setup snapshot either way.
  • Replicas periodically reconciles pool levels.
  • A scheduled automation gets a workspace a few minutes before it runs. Enabling a GitHub automation turns on its environment’s pool if none exists.
  • Edits queue a rebuild that starts after 45 seconds without further edits (at most 3 minutes after the first), so a burst of edits becomes one build. Workspaces keep starting from the previous build meanwhile. Start a queued build right away with Start now or build now; a build made obsolete by a newer edit is stopped.
  • A warm hook that fails is not retried until you change something or select Try again. Failures on our side retry on their own. Ready capacity rotates to stay fresh around the hours your team usually starts workspaces; outside them, older pre-warmed workspaces still start warm, a little slower.
  • Pools rebuild when something a pre-warmed workspace already contains changes: the warm hook, files, skills, skill registries, default skills, repositories, or a deleted or renamed variable. New and edited variables and agent credentials rebuild only pools with a warm hook, since only a warm hook can read them. The system prompt, personal preferences, start hook, and MCPs apply when a workspace is claimed and never rebuild. Repository-level warmHook edits in replicas.json / replicas.yaml are picked up the next time a workspace warms; existing pre-warmed workspaces are not refreshed automatically.
When a change starts a new build, the previous one keeps serving until the replacement is ready, and keeps serving if it fails. See History to restore an earlier setup.

Start Hooks

Start hooks run shell commands at workspace startup, after the engine boots. The coding agent starts at the same time and is told to wait for them before running anything that needs their setup. Use them for runtime setup that shouldn’t be baked into the warm pool snapshot: starting dev servers, applying database migrations, or pulling the latest data.

Levels

Start hooks from the enabled setup sources layer in a fixed order, mirroring warm hooks: Configure level 1 by opening an environment and editing the Start hook under Setup; a fork shows its ancestors’ hooks read-only above its own. Level 2 is committed alongside the code (see Repository Configuration). Save an empty environment script to clear the active start hook. The environment overview shows repository configuration errors directly on the Start hook row. Hover the truncated error to inspect the full message.

Execution order

At workspace startup, the engine runs start hooks in this order:
  1. Environment start hooks, starting with the root, then each ancestor, then the selected environment
  2. Repository start hook(s), one per cloned repo that defines a startHook in its config file
Environment start hooks run in the home folder (~), not in ~/workspaces like environment warm hooks, so refer to a repository as ~/workspaces/<repo>. Each repository start hook runs in its repository’s folder. A failure in the environment-level hook does not prevent repository hooks from running. Each repository hook runs independently and logs its output to ~/.replicas/startHooks.log. A start hook that connects a VPN or adds firewall rules must keep Replicas’ connection to the workspace working. See Start hooks that change networking.

When to use each level

  • Parent environment - runtime setup every fork needs (auth refresh, service registration).
  • Environment - setup specific to one environment (start a dev server with environment-specific flags, run migrations against a staging database).
  • Repository - setup that belongs with the code: npm run dev, docker compose up, etc. Commit it in replicas.json / replicas.yaml so it travels with the repo.

Repository-level config

Add a startHook field to your replicas.json or replicas.yaml:
timeout is in milliseconds (default 5 minutes). separate controls whether commands stop on first failure (true, default) or run as a combined script (false). See Repository Configuration for the full file schema.

Testing

The start hook editor includes a Test button that provisions an isolated sandbox, runs your script, and streams output in real time. Use it to verify a hook works before saving. The test sandbox is torn down automatically after the run completes.

CLI management

Start hooks can also be managed from the command line with replicas env start-hooks {get,save,test,repository-hooks}. See the CLI reference for the full command list.