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.
.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 withreplicas 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
.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-levelskills/*/SKILL.md, root-levelSKILL.md, and.claude-plugin/plugin.jsonmanifests - Skills are symlinked into
~/.claude/skills,~/.codex/skills, and~/.agents/skillsat provisioning time for Claude, Codex, Muse, Pi, and Opencode-compatible runtimes, and into~/.gemini/config/skillsfor 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
Default skills
Replicas auto-installs thereplicas-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 viewerdocker: start the daemon, build / run containers, drivedocker composegithub: pre-authenticatedghCLI for PRs, issues, releases, and GraphQLgitlab: pre-configuredgitcredentials for GitLab, used to push, pull, and open merge requests viagit pushoptionslinear: fetch issues, post comments, update state via the Linear APImedia: share screenshots, recordings, generated images, and audio clipsplugins: call installed marketplace tools from TypeScript (see Plugins)previews: expose locally running services on public preview URLsreplicas: use the in-workspacereplicasCLI to manage automations / envs / filessentry: read projects and issues via the Replicas gateway (see Sentry)slack: send messages, read threads, search conversations, transfer files
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 loadstdioand streamablehttpMCPs;sseis 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
httporsseMCP can authenticate with a workspace identity token instead of a stored header by settingconfig.authto{ "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 localstdioserver. 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.authset to{ "type": "oauth" },httponly). 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’sX-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.
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:- Environment warm hooks, starting with the root, then each ancestor, then the selected environment, each in its own subshell
- Repository warm hook(s), one per cloned repo, alphabetical by repo name
~/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 awarmHook 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
warmHookedits inreplicas.json/replicas.yamlare picked up the next time a workspace warms; existing pre-warmed workspaces are not refreshed automatically.
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:- Environment start hooks, starting with the root, then each ancestor, then the selected environment
- Repository start hook(s), one per cloned repo that defines a
startHookin its config file
~), 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 inreplicas.json/replicas.yamlso it travels with the repo.
Repository-level config
Add astartHook 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 withreplicas env start-hooks {get,save,test,repository-hooks}. See the CLI reference for the full command list.