Skip to main content

​
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

{
  "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: 
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

​
Fields

  • warmHook (optional) - object containing shell commands to run during pre-warming. Same schema as startHook:
    • timeout (optional) - timeout per command in milliseconds. Defaults to 300000 (5 minutes).
    • commands - array of shell commands. Commands run sequentially during warm pool creation. Ideal for slow installs and builds.
  • startHook - object containing shell commands to execute when the workspace starts:
    • timeout (optional) - timeout per command in milliseconds. Defaults to 300000 (5 minutes).
    • commands - array of shell commands. Commands run sequentially in the workspace directory. Perfect for installing dependencies, building projects, or running setup scripts.
  • systemPrompt (optional) - custom instructions for coding agents in the workspace.

​
Start hooks

Start hooks run automatically when the engine starts up. Commands execute sequentially in the workspace directory with a 5-minute timeout per command. If a hook fails, subsequent hooks still run and don’t block startup.

​
Warm hooks

Warm hooks run during pre-warming, before a workspace is assigned to a user. Use them for expensive setup like dependency installs and builds so workspaces provision instantly. See 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: 
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

​
Initializing a config file

Use the CLI to create a config file: 
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.