Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.replicas.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
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
To run all commands as a single script with shared shell state, set separate: false: 
warmHook:
  separate: false
  commands:
    - npm install
    - npm run build

​
Fields

  • warmHook (optional) - object containing shell commands to run during pre-warming. Same schema as startHook:
    • 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 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.

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