Skip to main content
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 six states:
StateDescription
BootingVM starting, cloning repo, installing dependencies
ProvisioningWaking from sleep or finishing background setup before becoming awake
AwakeReady for messages, agent working
SleepingPaused, no charges accrue
ArchivedPaused for retention, no charges accrue
FailedSetup/provisioning failed, a wake/resume attempt failed, or the underlying sandbox died. Wake failures show a Retry button that clears the error and re-attempts wake. If retry does not recover the workspace, reach out to founders@replicas.dev 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. The queue is expanded by default so you can see everything waiting. While Codex is mid-turn, each queued message shows a steer button that delivers that message into the active turn immediately instead of waiting for its place in the queue. If the turn can no longer be steered (for example it finished, or Codex is compacting), the message stays queued and runs normally. 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 are delivered server-side, so they arrive in order once the workspace is ready even if you navigate away or close the tab, staying visible in the thread meanwhile. Inline images send 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 appears in the Provenance Pane beside Changes and All files as soon as the workspace is ready. No agent action is required. The viewer is tuned for low-latency streaming and keeps the desktop at 1080p or higher. 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 Fast, Balanced, and Crisp presets plus reload and open-in-new-tab controls, so you can watch the agent click, type, and navigate in real time. The inline preview is watch-only; click Interact to open a full-screen modal where mouse and keyboard input drive the desktop. The desktop runs Linux, so use Ctrl instead of Cmd for shortcuts (Ctrl+C / Ctrl+V). Mac users get an in-viewer reminder when they press Cmd. Set REPLICAS_DESKTOP_RESOLUTION=2560x1440 or 3840x2160 before the desktop starts to run a larger workspace desktop. 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 Changes (files modified by the agent with inline diffs), All files (full codebase tree with search), and Desktop when the workspace desktop preview is available. File paths mentioned in agent messages open in Canvas for canvas files or the provenance pane for repo files.
  • 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 surfaces workspaces that aren’t your own, with a “team” badge and creator tooltip, when an admin enables Workspace Visibility in Preferences → Organization → Settings → Defaults. Toggle Team Workspaces from the Views submenu of the filter menu, or pick a specific teammate from the Owner submenu to scope to their workspaces.
  • API & Automations view surfaces non-human-owned workspaces (API and automation runs). Off by default; toggle on from the filter menu.
  • Sidebar actions: Each environment row shows inline icons to create a workspace or edit the environment.
  • Compact workspace rows: Workspaces render as single rows (activity status dot, name, archive, and the actions menu) indented under their environment. Hover a row to preview its branch/PR state and latest agent message. Pin workspaces to float them to the top, or rename them from the actions menu or by double-clicking a row.
  • Sidebar filters & sorting: The filter button opens a menu with Sort by (last activity, created date, status, or custom drag order), Organize sidebar (chronological flat list, environments, or recent environments), and hover submenus for Views, Status, Last activity, and Owner. Owner lists every member you can see workspaces from. Selections AND-combine and persist per-org; Reset filters clears filters, views, sort, and organization to their defaults. Pins and custom order are local to your browser and account. Dragging a workspace switches to custom order; choosing another sort clears that custom order.
  • Global search (Cmd/Ctrl+K): jump to any dashboard page, workspace, automation, or environment from anywhere in the dashboard.
  • 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 accepts /goal <objective> to set a goal for the thread (max 4000 characters), /goal pause, /goal resume, and /goal clear (or /goal reset / /goal unset). The active goal is sent to Codex and surfaces back in the dashboard as a composer goal bar and chat tab indicator. Expand the goal bar to read the full objective, edit it, pause or resume it, or delete it. Codex chats also include a goal-mode toggle button in the composer as an alternative to typing /goal. On Codex chats and Claude Opus model 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 Environments from the sidebar.

​
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: Workspaces that have been sleeping with no activity for 7 days are marked archived. You can also archive a workspace from the dashboard. Archived workspaces move out of the normal dashboard list into the archived view, stay paused, and can still be opened, messaged, or woken. Auto-delete: Archived workspaces with no activity for 30 days are automatically deleted. To keep a workspace alive past that window, send it a message or wake it. That counts as activity and resets the clock. Any workspace can be permanently deleted directly from the dashboard sidebar actions menu (⋯ → Delete) after confirmation, without archiving it first. Bulk actions: Use the select (checkbox) button in the workspace list toolbar to select multiple workspaces at once, then archive them or permanently delete them together. Bulk delete is confirmed with a dialog before it runs. 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. On the default pause mode the desktop session survives sleep, so running processes and open Chrome tabs are still there on wake. The desktop stack finishes booting a few seconds after the workspace goes active, so the Desktop tab may briefly show a connecting/starting placeholder before the live viewer reconnects. You can send messages to sleeping or archived workspaces and they’ll wake automatically to process your message. Suspended context: Sleeping and archived workspaces retain their branch and PR information in the dashboard, so you can tell which PR each one was working on without waking it. Workspace history is also viewable without waking. See Data Retention.

​
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:
ReasonMeaning
timeoutThe engine didn’t answer within 10 s. Usually a transient stall under heavy load.
network_errorThe connection itself failed (DNS, TLS, refused). Often a brief sandbox restart.
http_statusThe engine answered with a non-2xx status (e.g. 503 while the engine is still booting).
wrong_content_typeThe 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 founders@replicas.dev. Failed: Setup/provisioning failures, such as repository clone/auth errors, leave the workspace in an error state with the underlying message shown in the dashboard. Wake/resume failures also surface here and show a Retry button that clears the error and tries to wake the workspace again. If retry does not recover the workspace, or the underlying sandbox died unrecoverably, reach out to founders@replicas.dev.

​
Billing

Workspaces are billed only while active, in minutes of runtime. No charges accrue while sleeping or archived. On paid plans, manual 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; defaults to small). Hobby orgs that exhaust their monthly minutes have running workspaces suspended (never deleted) until the allowance resets. See Billing for the full breakdown.