> ## 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.

# Repository Config

> Configure environment setup on workspaces.

# Configure repositories with `replicas.json` or `replicas.yaml`

Replicas looks for a configuration file at the root of your Git repository. It runs setup commands when workspaces start, so every agent begins with the right dependencies and environment.

Supported filenames (checked in order):

1. `replicas.json`
2. `replicas.yaml`
3. `replicas.yml`

If multiple config files exist, only the first one found is used.

## File schema

### JSON format

```json theme={null}
{
  "systemPrompt": "**Environment Note:** This is a production codebase. Always write tests for new features.",
  "warmHook": {
    "timeout": 300000,
    "commands": [
      "npm install",
      "npm run build"
    ]
  },
  "startHook": {
    "timeout": 300000,
    "commands": [
      "./scripts/setup.sh"
    ]
  }
}
```

### YAML format

YAML is especially useful for multiline system prompts:

```yaml theme={null}
systemPrompt: |
  **Environment Note:** This is a production codebase.
  Always write tests for new features.

  ## Guidelines
  - Follow the existing code style
  - Run `npm test` before committing
  - Use TypeScript strict mode

warmHook:
  timeout: 300000
  commands:
    - npm install
    - npm run build

startHook:
  timeout: 300000
  commands:
    - ./scripts/setup.sh
```

To run all commands as a single script with shared shell state, set `separate: false`:

```yaml theme={null}
warmHook:
  separate: false
  commands:
    - npm install
    - npm run build
```

## Fields

* `warmHook` *(optional)* - object containing shell commands to run during [pre-warming](/features/environments#warm-hooks). Same schema as `startHook`:
  * `timeout` *(optional)* - timeout in milliseconds. Defaults to 3600000 (60 minutes), capped at 7200000 (120 minutes). Applies per individual command by default. When `separate: false`, this is the timeout for the entire combined script.
  * `commands` - array of shell commands. Commands run sequentially during warm pool creation. Ideal for slow installs and builds.
  * `separate` *(optional)* - defaults to `true`. Each command runs in its own shell process with an independent timeout. Set to `false` to run all commands as a single script in one shell session, sharing environment variables and working directory changes between commands.
* `startHook` - object containing shell commands to execute when the workspace starts:
  * `timeout` *(optional)* - timeout in milliseconds. Defaults to 300000 (5 minutes). Applies per individual command by default. When `separate: false`, this is the timeout for the entire combined script.
  * `commands` - array of shell commands. Commands run sequentially in the workspace directory. Perfect for installing dependencies, building projects, or running setup scripts.
  * `separate` *(optional)* - defaults to `true`. Each command runs in its own shell process with an independent timeout. Set to `false` to run all commands as a single script in one shell session, sharing environment variables and working directory changes between commands.
* `systemPrompt` *(optional)* - custom instructions for coding agents in the workspace.

## Start hooks

Start hooks run automatically when the engine starts up. Each command runs in its own shell process by default, with a 5-minute timeout per command. Set `separate: false` to run all commands as a single script in one shell session where environment variables, `cd` changes, and other shell state carry over between commands.

Environment-level start hooks configured in [Environments](/features/environments#start-hooks) run before repository-level hooks defined here.

## Warm hooks

Warm hooks run during pre-warming, before a workspace is assigned to a user. Like start hooks, each command runs in its own process by default. Set `separate: false` to run them as a single script with shared shell state. Use warm hooks for expensive setup like dependency installs and builds so workspaces provision instantly. See [Warm Hooks](/features/environments#warm-hooks) for full details on warm pools, execution order, and limits.

## System prompts

The `systemPrompt` field provides custom instructions that agents follow throughout the workspace.

YAML's block scalar syntax (`|`) makes long system prompts easy to read and maintain:

```yaml theme={null}
systemPrompt: |
  You are working on the Acme API.

  ## Rules
  - Always write tests for new endpoints
  - Use the repository's ESLint config
  - Follow REST naming conventions
```

## Per-repo agent config

Files checked into the repo root are picked up automatically across all coding agents in the workspace:

* `.claude/skills/`, `.codex/skills/`, and `.agents/skills/`: skills available to Claude, Codex, Cursor, Opencode, and Pi sessions where supported by the agent runtime
* `.claude/agents/`: subagent definitions
* `.claude/hooks/`: Claude Code hooks
* `CLAUDE.md` and `AGENTS.md`: repo-level instructions appended to the system prompt

This works for every repo cloned into the workspace, so multi-repo workspaces compose skills and instructions from each repo together.

## Initializing a config file

Use the CLI to create a config file:

```bash theme={null}
replicas init          # Creates replicas.json
replicas init --yaml   # Creates replicas.yaml with multiline support
```

## Best practices

* **Commit your config file to your repo** so all workspaces use the same setup.
* **Use `warmHook` for slow installs and builds**, and keep `startHook` lightweight for session-specific setup.
* **Keep `startHook` commands fast.** Agents wait for setup to complete before starting work.
* **Test hooks locally** before committing to ensure they work on CI systems too.
* **Use YAML format** if your system prompt is long or multiline — it's easier to read and maintain.