Overview

How workspaces run and manage themselves.

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 five states:

State	Description
Booting	VM starting, cloning repo, installing dependencies
Provisioning	Waking from sleep or finishing background setup before becoming awake
Awake	Ready for messages, agent working
Sleeping	Paused, no charges accrue
Failed	Terminal state: the underlying sandbox died unrecoverably (e.g. out of memory during a heavy build). The workspace cannot be woken or messaged. Reach out to [e-mail] for help.

When the focused workspace fails, the browser tab shows a red X badge on the favicon so you can spot it in a stack of tabs.

Workspace config controls per-workspace behavior. Use the config button on a workspace in the sidebar, or set config.capabilities and config.preferences through the API, to allow PR follow-ups or keep a PR workspace open after its tracked PR is merged.

What Runs Inside

Each workspace runs the Replicas Engine on port 3737, which:

• Manages Claude Code, Codex, Cursor, and Opencode agent sessions
• Queues messages when agents are busy
• Handles git operations (branch creation, commits)
• Refreshes authentication tokens automatically; use the refresh button next to Codex in the workspace Overview tab when you reconnect a different account
• Supports Docker for running containerized development services inside the workspace

Messages sent while an agent is processing are queued and executed in order. Bursts of GitHub events of the same kind (CI failures, PR comments, PR reviews) that pile up while the agent is busy are folded into a single queued entry so the agent handles them in one combined turn. Bundled entries show up in the queue panel with an N messages badge.

The composer stays typeable during workspace initialization. Messages sent while booting queue locally and deliver in order when ready, staying visible in the thread meanwhile. Inline images queue with the message; file attachments are disabled until the workspace is ready.

Background tasks

Background tasks spawned by Claude (Monitor, background Bash, background Agent) appear as status indicators in the agent transcript. Each indicator shows a live state (in progress, completed, failed, or stopped) so you can track long-running operations without scrolling through raw output.

Click a background task row to expand it: the panel shows the original prompt, the latest activity, the last tool used, the output file path, and resource usage (tools, time, tokens). Errors appear inline in red.

Background tasks outlive the turn that spawned them: Replicas keeps the underlying Claude session open across user turns, so a Monitor watching a build or log file can fire minutes later and Claude will wake up and react within the same conversation.

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

Desktop tab

Every workspace boots with a Linux desktop (Xvfb at 1920×1080 by default, openbox, Chrome, ffmpeg, x11vnc, noVNC). The engine auto-registers the noVNC viewer as an authenticated preview at startup, so the Desktop tab in the dashboard is live alongside Chat and Plan as soon as the workspace is ready. No agent action is required. The viewer is tuned for low-latency streaming. Agents can fetch the viewer URL with replicas computer info to share it out-of-band (e.g. paste it into a Slack reply).

The tab embeds the authenticated noVNC viewer with reload and open-in-new-tab controls, so you can watch the agent click, type, and navigate in real time. Only logged-in Replicas users can access the viewer URL.

Collaboration and Review

• Create multiple chats per workspace to split workstreams and keep context organized. Drag tabs to reorder them.
• 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.
• The Provenance Pane sits alongside the chat on desktop and offers two lenses: Changes (files modified by the agent with inline diffs) and All files (full codebase tree with search). File paths mentioned in agent messages are clickable and open an inline file viewer.
• In the Provenance Pane’s Changes lens, click a diff gutter to attach an inline comment to a specific line. Saved comments appear inline with edit, hide, and remove controls, queue as composer context, and are sent to the agent with the file, line, and code snippet.
• 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 workspaces created by other organization members, with a “team” badge and creator tooltip. Externally-triggered workspaces (Slack/Linear/GitHub/GitLab) are attributed to the user who triggered them: ones you triggered show by default, and ones triggered by a teammate (or whose triggering user can’t be resolved to a Replicas account) appear here. Toggle Team Workspaces from the Views row of the filter popover, or pick a specific teammate from the Owner row to scope to their workspaces. Admins can enable this view in Organization Settings → Defaults → Workspace Visibility.
• API & Automations view surfaces non-human-owned workspaces (API and automation runs). Off by default; toggle on from the filter popover.
• Sidebar counts: Each environment group shows a count badge. Click for a per-status breakdown.
• Sidebar filters: The filter button opens a popover with Views, Status, Last activity, and Owner. Owner lists every member you can see workspaces from. Selections AND-combine and persist per-org.
• Trigger Rebase on main or Merge in main from the workspace card’s actions menu (the ⋯ button, under Sync with main). The selected option is sent as a message to the active agent chat, so the agent performs the operation on the workspace’s branch.

Chat commands

The composer accepts /compact on Claude chats, which routes the slash command into the Claude Agent SDK so Claude Code performs its native in-session compaction (the session id is preserved and the prefix is rewritten in place). Codex chats no longer special-case /compact; Codex auto-compacts at ~90% of the context window, so manual invocation isn’t needed.

On Codex chats, the composer also accepts /goal <objective> to set a goal for the thread (max 4000 characters) and /goal clear (or /goal reset / /goal unset) to clear it. The active goal is sent to Codex and surfaces back in the dashboard as a goal indicator on the composer and the chat tab so you can see what the agent is currently working toward. Codex chats also include a goal-mode toggle button in the composer as an alternative to typing /goal.

On Claude and Codex chats, /fast enables fast mode, which switches the agent to a faster service tier for subsequent turns. Cursor uses its configured Composer model directly, and Opencode does not currently support fast mode. The composer also includes a lightning bolt toggle button as an alternative to typing the command. See Fast Mode for details.

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-delete: Workspaces that have been sleeping with no activity for 7 days are automatically deleted. To keep a workspace alive past that window, send it a message or open it. That counts as activity and resets the clock.

Wake behavior: When a workspace wakes, it enters the preparing state while the sandbox resumes and the engine reconnects in the background. The dashboard reflects activation as soon as it completes, even for large workspaces that take a while. Wake requests are idempotent, so repeated clicks or reloads while a wake is already in progress join the in-flight wake instead of starting a second one. If a wake is interrupted and the workspace stays in preparing for more than 10 minutes, the next wake request treats it as stale and retries. Once active, the workspace resumes the previous agent session and git branch. You can send messages to sleeping workspaces and they’ll wake automatically to process your message.

Sleeping context: Sleeping workspaces retain their branch and PR information in the dashboard sidebar, so you can tell which PR each one was working on without waking it. Workspace history is also viewable without waking. See Workspace History.

Troubleshooting

“Workspace engine is temporarily unavailable / Engine health check failed (…)”: Replicas pings the workspace’s engine before showing live state. If the probe fails, the banner appears with the underlying reason in parentheses:

Reason	Meaning
timeout	The engine didn’t answer within 10 s. Usually a transient stall under heavy load.
network_error	The connection itself failed (DNS, TLS, refused). Often a brief sandbox restart.
http_status	The engine answered with a non-2xx status (e.g. 503 while the engine is still booting).
wrong_content_type	The response wasn’t JSON. Typically an edge-proxy error page slipping through.

The banner usually clears on its own within a few seconds. If it persists, reload the page; the workspace state on disk is unaffected. If it persists across reloads, the workspace itself is likely unhealthy. Reach out to [e-mail].

Billing

Workspaces are billed only while active. No charges accrue while sleeping. Interactive workspaces are covered by your per-seat subscription. API and Automation workspaces accept a size field (small at $0.008/min, large at $0.016/min); calls that omit size keep the legacy $0.0166/min rate. See Billing for the full breakdown.