Skip to main content

​
Prerequisites

  • Create an account at replicas.dev and confirm email access. Workspaces live behind your organization settings.
  • Install the Replicas CLI and authenticate:
npm i -g replicas-cli
replicas login
  • (Optional) Install a VSCode-compatible IDE such as Cursor if you plan to open workspaces graphically via replicas code.
For the beta, we’re focusing on first-party support for GitHub, Codex as the bundled agent, and VSCode-family IDEs. Others (like Claude Code) are coming quick!

​
Watch the flow

​
Step-by-step walkthrough

​
1. Add an SSH key

Head to Connections → SSH Keys in the dashboard and upload your public key. You can download the generated .pem from the UI, but running replicas connect will also fetch the key automatically. SSH Key Screenshot

​
2. Capture your template

Open Templates and create a template describing what every workspace should boot with:
  • Connect the Replicas GitHub App and select a repository (one per template)
  • Optional Git identity to commit from the VM
  • Pre-install Codex and supply authentication
  • Shell commands to run after cloning (install dependencies, seed data, etc.)
Template Screenshot Template Screenshot 2
All sensitive information (GitHub App tokens, private keys, and agent credentials) are encrypted in Supabase Vault. We only access them when provisioning your workspace.

​
3. Launch a workspace

From the dashboard, click Create Workspace. Pick your template, select the SSH key, and choose an instance size that matches your task (see credits for sizing tips). Give it a short slug (letters, numbers, dashes). The template ensures both you and the agent land in an environment with the same tooling. Workspace Screenshot

​
4. Provision workspace

Replicas spins up the VM, clones the repo(s), installs dependencies, and runs your custom commands. When ready you’ll see the external IP, region, and logs. Workspace Ready Screenshot

​
5. Connect with the CLI

Pick the workflow that fits: 
# Standard SSH session with automatic port forwarding.
replicas connect my-workspace --copy

# Open directly in Cursor/VSCode using Remote SSH.
replicas code my-workspace --copy
The --copy flag reads your repo’s replicas.json file and syncs secrets or config files before the session starts. It also tethers any ports you define (e.g., 3000 for web, 5432 for Postgres) to available local ports so your agent can serve traffic while you review locally.
Workspace VMs are locked to interactive engineering workloads. Mining, open relay services, and inbound-heavy traffic are blocked and violate our terms of service.

​
Where to go next

⌘I