> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryreplicas.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Environments
> Configure variables, files, skills, MCPs, start hooks, and warm hooks for your workspaces.
Configure what gets injected into workspaces from **Environments** in your dashboard sidebar. Each environment has its own tabs for Configuration, Variables, Files, Skills, MCPs, Start Hooks, Warm Hooks & Pools, Settings, and (behind the `learnings` flag) [Learnings](/features/learnings).
Everything below is also available through the [Replica API](/features/api#environments-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 team and personal 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 a team environment, it receives Global merged underneath that environment. 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 standalone personal environment receives Global first, then a matching team environment by repo binding when one exists, then personal values. A source-backed personal environment receives Global first, then the source team environment, then the personal additions. Source and Global values stay locked; personal additions cannot use the same file path, MCP name, skill, registry URL, or secret-sync provider. Variable keys are locked unless an admin marks the inherited variable overrideable.
In the dashboard, team environments appear under **Team** and personal environments appear under **Personal**. Create from **Team** for a team environment or **Personal** for a personal environment. The new environment popover has a **Source** picker for Plain vs copying an existing environment for team environments, or Plain vs inheriting from a team environment for personal environments.
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. Source-backed personal environments inherit repository binding, system prompt, warm pools, variables, files, skills, skill registries, MCPs, and Doppler/Infisical connections from their source. Personal warm hooks and start hooks remain additive.
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.
Source-backed personal environments can't edit the inherited system prompt, but can add **personal preferences** on the Configuration tab. These are instructions appended after the inherited prompt and relayed to the agent as the workspace owner's preferences (e.g., how you like information presented or code written). Environment instructions win on conflict.
## 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](/features/infisical) or [Doppler](/features/doppler). Manual variables take priority over integration secrets
* Admins can mark team or Global variables as overrideable by source-backed personal environments
* Source-backed personal environments show inherited variables as locked rows, with inline editing for overrideable keys
## 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](https://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/`. Pi discovers provisioned and repository skills through `.agents/skills/`; Opencode can use `.agents/skills/` where supported by its runtime. See [per-repo agent config](/features/workspaces/repository-configuration#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, Pi, 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, Pi, and Opencode-compatible runtimes
* 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 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 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
* `google`: create / edit Google Docs, Sheets, Forms and read Google Search Console data via the Replicas gateway
* `learnings`: pull curated org knowledge on demand and propose new entries for review (requires the `learnings` flag; see [Learnings](/features/learnings))
* `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](/features/mcp), 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](/features/slack) and [Linear](/features/linear) intake also pick an environment for the workspace they create. The env's binding determines which repository or repository set gets cloned. Users can set a personal default under [Personal → Preferences](https://tryreplicas.com/dashboard/account/preferences), and org admins can set a team default under [Organization → Settings → Preferences](https://tryreplicas.com/dashboard/settings?tab=defaults).
## 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 four 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 | **Source environment** | Warm Hooks tab on the source team environment | Source-backed personal environments |
| 3 | **Environment** | Warm Hooks tab on the selected team or personal environment | Pools for that environment |
| 4 | **Repository** | `warmHook` field in `replicas.json` / `replicas.yaml` at the repo root | Workspaces that clone that repo |
Levels 1–3 are configured in **Environments**. A source-backed personal environment shows the source hook read-only and provides a separate personal hook editor. Level 4 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. **Source environment** warm hook (source-backed personal environments only)
3. **Environment** warm hook, including the additive personal hook (skipped when the workspace runs in the Global env, since that's already step 1)
4. **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`:
```json replicas.json theme={null}
{
"warmHook": {
"timeout": 300000,
"commands": [
"npm install",
"npm run build"
]
},
"startHook": {
"timeout": 300000,
"commands": [
"npm run dev"
]
}
}
```
```yaml replicas.yaml theme={null}
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](/features/workspaces/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 and can be toggled off from the Warm Hooks tab. Personal environments start with warm pools off.
* Default pool size is 5. Contact [founders@replicas.dev](mailto:founders@replicas.dev) to increase.
* Replicas periodically reconciles pool levels.
* If a pool becomes stale, the Warm Hooks tab explains the problem instead of showing the underlying sandbox error. Organizations without automatic warm-pool rotation can select **Refresh** to invalidate the stale generation and reconcile a fresh pool.
* 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](#warm-hooks).
### Snapshot history and restore
Snapshot-capable warm pools retain each successful generation. When a configuration change starts a new warmup, the previous snapshot continues serving and replenishing the pool until the replacement is ready. If the new warmup fails, workspaces continue using that fallback generation.
Open **Environments → Warm Hooks → Snapshot History** to see retained versions, labelled `v1`, `v2`, and so on. Select **Restore** on an earlier version to serve it again without rerunning the warm hook; the **Current** badge moves onto that version and the pool refills from its snapshot. Restoring changes the pool snapshot, not the script in the warm-hook editor; a later invalidation rebuilds from the currently saved configuration.
## 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 four levels
Start hooks layer in a fixed order, mirroring [warm hooks](#warm-hooks):
| # | Level | Where it lives | Applies to |
| - | ---------------------- | ----------------------------------------------------------------------- | ----------------------------------- |
| 1 | **Global** | Start Hooks tab on the **Global** environment | Every workspace in the org |
| 2 | **Source environment** | Start Hooks tab on the source team environment | Source-backed personal environments |
| 3 | **Environment** | Start Hooks tab on a team or personal environment | Workspaces in that environment |
| 4 | **Repository** | `startHook` field in `replicas.json` / `replicas.yaml` at the repo root | Workspaces that clone that repo |
Levels 1–3 are configured in **Environments → Start Hooks**. A source-backed personal environment shows its source hook as read-only and provides a separate editor for its additive personal hook. Level 4 is committed alongside the code (see [Repository Configuration](/features/workspaces/repository-configuration)).
Save an empty Global or environment script to clear the active start hook.
### Execution order
At workspace startup, the engine runs start hooks in this order:
1. **Global** start hook
2. **Source environment** start hook (source-backed personal environments only)
3. **Environment** start hook
4. **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`:
```json replicas.json theme={null}
{
"startHook": {
"timeout": 300000,
"commands": [
"npm run dev"
]
}
}
```
```yaml replicas.yaml theme={null}
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](/features/workspaces/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](/features/cli#manage-start-hooks) for the full command list.