Skip to main content

​
Configure repositories with replicas.json

Replicas looks for a replicas.json file at the root of your Git repository whenever you run replicas connect or replicas code. It keeps secrets, assets, and tunnels consistent across every workspace spun up from that repo.

​
File schema

{
  "copy": [
    "web/.env.local",
    "scripts/setup.sh"
  ],
  "ports": [3000, 4173, 5432]
}
  • copy (optional) — array of file paths or glob patterns relative to the repo root. These files sync into the workspace before your shell opens. Directories are copied recursively.
  • ports (optional) — array of integers. Each port is forwarded from the workspace to your machine. The CLI finds open local ports automatically and prints the mapping.
Coming soon: command hooks so you can declare scripts (e.g., npm run dev) that run right after copy + tunneling.

​
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 the repo so everyone shares the same setup. Store sensitive values in the files referenced by copy, not in the JSON itself.
  • Pair replicas.json with template custom commands to auto-install dependencies before you connect.
  • Rotate secrets regularly. Replicas does not keep copies server-side once the session ends.
⌘I