Environments

Configure variables, files, skills, MCPs, start hooks, and warm hooks for your workspaces.

Configure what gets injected into workspaces from Settings → Environments in your dashboard. Each environment has its own tabs for Configuration, Variables, Files, Skills, MCPs, Start Hooks, Warm Hooks & Pools, and Settings.

Everything below is also available through the Replica API. The Global environment can be addressed as global in any URL — no UUID lookup required.

Environments

An organization has one Global environment (applied to every workspace) plus any number of named environments. Each non-global environment optionally binds to a repository or a repository set as a property.

Every variable, file, skill, and MCP belongs to a single environment. When a workspace runs in environment X, it receives Global merged underneath X. Values in X win on conflict.

Each non-global 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.

Variables

Key-value environment variables injected into workspaces at boot.

• Belong to a specific environment
• Values are encrypted at rest
• Paste .env-formatted blocks to batch add
• Secrets can also be synced from Infisical or Doppler. Manual variables take priority over integration secrets

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/. Opencode can use cross-agent .agents/skills/ where supported by its runtime. See per-repo agent config.

When an environment is bound to a repository or repository set, the Skills tab also lists the skills, agents, commands, and prompts committed to that repo under .claude/, .codex/, and .agents/ (read-only) so you can see at a glance what Claude, Codex, and Opencode-capable runtimes will pick up.

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, and Opencode-compatible runtimes
• Uses your organization’s GitHub credentials when available; falls back to anonymous access for public repos
• Add or remove registries from the Skills tab in environment settings

Default skills

Replicas auto-installs the replicas-agent skill (highly recommended) into every workspace so agents have a consistent baseline for Replicas-managed integrations. Audit and toggle it from the Skills tab on the Global environment. Each ability 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 noVNC 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
• google: create / edit Google Docs, Sheets, Forms via the Replicas gateway
• linear: fetch issues, post comments, update state via the Linear API
• media: share screenshots, recordings, generated images, and audio clips
• previews: expose locally running services on public preview URLs
• replicas: use the in-workspace replicas CLI to manage automations / envs / files
• slack: send messages, read threads, search conversations, upload 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.
• 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

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 the repository (or repository set) the automation targets, plus everything Global doesn’t already cover.

Pick the Global environment if the automation needs no extras beyond org-wide defaults. Otherwise pick the named environment whose repo / vars / MCPs / skills 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 binding determines which repository or repository set gets cloned. Org admins can set a default environment under Settings → Organization to skip the prompt.

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.

The three levels

Warm hooks layer in a fixed order. Each level is optional, and any combination can be set.

#	Level	Where it lives	Applies to
1	Global	Warm Hooks tab on the Global environment	Every pre-warm in the org
2	Environment	Warm Hooks tab on a named environment	Pools for that environment
3	Repository	warmHook field in replicas.json / replicas.yaml at the repo root	Workspaces that clone that repo

Levels 1 and 2 are configured in Settings → Environments. Level 3 is committed alongside the code.

Execution order

During pre-warming, the engine runs the hooks in this order, in the same workspace:

1. Global warm hook
2. Environment warm hook (skipped when the workspace runs in the Global env, since that’s already step 1)
3. Repository warm hook(s) — one per cloned repo, alphabetical by repo name

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

• Global — org-wide setup that every workspace 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:

replicas.json

{
  "warmHook": {
    "timeout": 300000,
    "commands": [
      "npm install",
      "npm run build"
    ]
  },
  "startHook": {
    "timeout": 300000,
    "commands": [
      "npm run dev"
    ]
  }
}

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 environments and can be toggled off from the Warm Hooks tab.
• Default pool size is 5. Contact [e-mail] to increase.
• Replicas periodically reconciles pool levels.
• Pools are automatically invalidated when an environment’s warm hook, variables, files, skills, MCPs, system prompt, repository default branch, or repository set membership changes. 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.
• The Warm Hooks tab streams live warm-hook output for each pre-warmed workspace while it warms. Click into a workspace row to watch hook stdout land as the pool fills, the same way you watch output when testing a warm hook.

Start Hooks

Start hooks run shell commands at workspace startup, after the engine boots and before the coding agent begins its task. 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.

The three levels

Start hooks layer in a fixed order, mirroring warm hooks:

#	Level	Where it lives	Applies to
1	Global	Start Hooks tab on the Global environment	Every workspace in the org
2	Environment	Start Hooks tab on a named environment	Workspaces in that environment
3	Repository	startHook field in replicas.json / replicas.yaml at the repo root	Workspaces that clone that repo

Levels 1 and 2 are configured in Settings → Environments → Start Hooks. Level 3 is committed alongside the code (see Repository Configuration).

Execution order

At workspace startup, the engine runs start hooks in this order:

1. Environment start hook (Global merged with the target environment; Global runs first, then the target environment’s hook)
2. Repository start hook(s), one per cloned repo that defines a startHook in its config file

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.

When to use each level

• Global - runtime setup every workspace 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:

replicas.json

{
  "startHook": {
    "timeout": 300000,
    "commands": [
      "npm run dev"
    ]
  }
}

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 Hooks tab 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.