Skip to main content

​
Configure repositories with replicas.json

Replicas looks for a replicas.json 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.

​
File schema

{
  "copy": [
    "web/.env.local",
    "scripts/setup.sh"
  ],
  "ports": [3000, 4173, 5432],
  "systemPrompt": "**Environment Note:** This is a production codebase. Always write tests for new features.",
  "startHook": {
    "timeout": 300000,
    "commands": [
      "./scripts/setup.sh",
      "npm install"
    ]
  }
}
  • 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.
  • copy (optional) - array of file paths or glob patterns to sync from your local machine. Useful for environment files and secrets.
  • ports (optional) - array of ports to tunnel from the workspace to your machine. Useful for accessing web apps and services locally.

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

​
System prompts

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

​
Additional features

​
Port tunneling

Forward workspace ports to your local machine for testing: 
"ports": [3000, 5432, 6379]
The CLI automatically tunnels each port and prints the local mapping.

​
File syncing

Copy environment files and secrets from your machine into the workspace: 
"copy": [".env.local", "config/secrets.json"]
Run replicas connect --copy to sync files via scp.

​
How copying works

  1. Run replicas connect my-workspace --copy.
  2. The CLI confirms you are inside a Git repo and locates replicas.json.
  3. Each copy entry is validated; missing files are flagged but do not stop the session.
  4. Files are uploaded via scp to the workspace path /home/ubuntu/workspaces/<repo-name>/.
Keep secrets like .env out of Git and in your local filesystem. You decide when they sync to the VM.

​
How port tunneling works

  • For every port in ports, the CLI adds an SSH tunnel (-L local:remote).
  • If a port is taken locally, Replicas picks the next free one and prints remote 3000 → local 3001.
  • Tunnels stay alive as long as your connect or code session is active.
This keeps web apps, websocket servers, and databases accessible from tools running on your laptop.

​
Best practices

  • Commit replicas.json to your repo so all workspaces use the same setup.
  • Store secrets in files referenced by copy, not directly in the JSON.
  • 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.