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.

Workspaces are isolated virtual machines with your repository cloned and a coding agent ready to work. Each workspace runs the Replicas Engine, which manages agent sessions, message queues, and git operations.

​
Lifecycle

Workspaces move through three states:
StateDescription
BootingVM starting, cloning repo, installing dependencies
ActiveReady for messages, agent working
SleepingPaused, no charges accrue

​
What Runs Inside

Each workspace runs the Replicas Engine on port 3737, which:
  • Manages Claude Code and Codex agent sessions
  • Queues messages when agents are busy
  • Handles git operations (branch creation, commits)
  • Refreshes authentication tokens automatically
  • Supports Docker for running containerized development services inside the workspace
Messages sent while an agent is processing are queued and executed in order.

​
Docker

Docker is installed in every workspace, but the daemon does not start automatically. Agents are guided to start it on demand via the replicas-agent skill: 
sudo service docker start
until docker info >/dev/null 2>&1; do sleep 0.2; done
The until loop waits for the Docker socket to be ready before proceeding. Without it, commands that use Docker immediately after starting the daemon may fail because the socket isn’t accepting connections yet. If you want the daemon ready as soon as the workspace boots, add it to your start hook in replicas.json or replicas.yaml:
replicas.yaml
startHook:
  commands:
    - sudo service docker start && until docker info >/dev/null 2>&1; do sleep 0.2; done

​
Collaboration and Review

  • Create multiple chats per workspace to split workstreams and keep context organized.
  • Use the built-in Diff Viewer to inspect pending code changes without leaving the dashboard.
  • Use the Files view to browse workspace files directly in the dashboard.
  • Share workspaces with teammates so they appear in the “Shared” sidebar view. Sharing controls sidebar visibility. All organization members already have full access to all workspaces.
  • Team Workspaces view shows dashboard workspaces created by other organization members, with a “team” badge and creator tooltip. This lets you discover teammates’ workspaces without requiring an explicit share.
  • Trigger Rebase on main or Merge in main from the workspace row. The selected option is sent as a message to the active agent chat, so the agent performs the operation on the workspace’s branch.

​
Repository Targeting

Workspaces can run against one repository or multiple repositories.
  • Select individual repositories during workspace creation.
  • Use Repository Sets to save common multi-repository combinations and reuse them quickly.

​
Environment Configuration

Every workspace runs inside a single environment. Each org has one Global environment plus any number of named environments that optionally bind a repository or repository set. Variables, files, skills, MCPs, and the system prompt all flow from the workspace’s environment, merged on top of Global. See Environments for the full model and how to create one. Open settings at Environment.

​
Warm Pools

Pre-warm workspaces by running setup scripts ahead of time, so new workspaces provision instantly from a ready pool. Warm hooks are configured per environment via replicas.json or replicas.yaml. See Environments for details.

​
Sleep and Wake

Auto-sleep: Workspaces sleep after 1 hour of inactivity. Auto-archive: Sleeping workspaces are archived after 7 days of inactivity. Auto-delete: Automatic sandbox deletion is currently disabled. Wake behavior: When a workspace wakes, it resumes the previous agent session and git branch. You can send messages to sleeping workspaces and they’ll wake automatically to process your message.

​
Billing

Workspaces are billed only while active. No charges accrue while sleeping. Interactive workspaces are covered by your per-seat subscription, and API or Automations workspaces are metered at $0.0166/min. See Billing for the full breakdown.