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: 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. A workspace started from Slack or Linear shows a link back to the thread or issue that started it in the workspace header, next to the pull request actions. On narrow screens the link moves into the header’s actions menu. Linear links are labelled with the issue identifier, such as REP-398. The API returns the same link as source_link on each workspace.

​
What Runs Inside

Each workspace runs the Replicas Engine on port 3737, which:
  • Manages Claude Code, Codex, Cursor, Opencode, and Pi 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. Open a queued message’s actions menu to edit it before processing starts. While Codex or Claude is mid-turn, each queued message shows a steer button instead of waiting for its place in the queue. Codex delivers the message into the active turn; Claude stops the active turn and starts the selected message next. 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, and you can create chat tabs and send messages while a new, booting, or preparing workspace still starts up. These pending chats and messages are queued server-side and delivered in order once startup completes, even if you navigate away or close the tab. The prompt starting the workspace appears in the thread; follow-ups remain in the queue and enter chat history only when their turns start. The same applies to sleeping workspaces: messaging one queues your input and wakes it automatically. The unified paperclip control lets you add images, files, and folders to the composer while the workspace is still provisioning.

​
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:
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

​
Desktop tab

Every workspace boots with a Linux desktop (Xvfb at 1920×1080 by default, openbox, Chrome, PulseAudio, and ffmpeg). The engine auto-registers its H.264 and Opus stream as an authenticated preview, so the Desktop tab appears in the Provenance Pane beside Changes and All files as soon as the workspace is ready. The encoder starts on demand and is shared by concurrent viewers. Agents can fetch the viewer URL with replicas computer info to share it out-of-band. The inline preview is watch-only; click Interact to open a full-screen view where mouse, keyboard, wheel, and audio work directly. Click Enable audio if your browser blocks autoplay. The desktop runs Linux, so use Ctrl instead of Cmd for shortcuts (Ctrl+C / Ctrl+V). 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.

​
Terminal tab

Open Terminal beside Canvas and Subagents to run an interactive shell inside an awake workspace. Use + to create independent sessions and close a session from its tab.

​
Keyboard shortcuts

Cmd uses Ctrl on Windows or Linux. Open the full reference from Help → Keyboard Shortcuts or press Cmd + /. Every shortcut stays available while composing, so workspace and chat navigation still work with the cursor in the composer. Cmd + / toggles the reference open and closed. Other shortcuts do not run inside dialogs, and none run during IME composition.

​
Collaboration and Review

  • The workspace header combines the pull request link and current lifecycle status in one control. Its actions menu can close a single GitHub pull request, convert an open pull request to a draft, or mark a draft ready for review directly through GitHub without consuming an agent turn. When an open pull request passes CI without conflicts and GitHub reports it as mergeable, the green Ready state becomes the merge action (under the actions menu on mobile). Pull requests held back by branch protection show Merge blocked instead, and branches behind their base show Out of date, so the merge action only appears when GitHub will actually accept it. After confirmation, the workspace engine runs GitHub CLI with the configured credential. Required reviews, branch protection, conflicts, and permissions still apply. The merge action is unavailable when the organization enables PR merge blocking. With PR attribution, the merge uses the workspace owner’s connected GitHub account.
  • Create multiple chats per workspace to split workstreams and keep context organized. Before the first turn, changing the harness, model, or effort updates an unsent chat locally without creating a persisted chat tab. Empty workspaces preserve the selected coding agent and Untitled chat when you navigate away and return. The chat is persisted when you send its first message; after that, the picker stays scoped to the chat’s model and effort. Unused default agent tabs stay hidden until first use. Drag tabs to reorder them.
  • Use the left-side message navigator in wider chats to preview user turns and jump directly to them.
  • Delete any chat tab from its context menu, except the last open one; deleting a mid-turn chat stops its running turn. Deleted chats stay restorable from the tab strip’s history menu.
  • Use the built-in Diff Viewer to inspect pending code changes without leaving the dashboard.
  • Use the workspace header’s Info control to open preview links and inspect environment details. Coding agents and integrations are collapsed by default and expand on click.
  • Opening a workspace records it for that organization. The dashboard landing page shows up to five recent workspaces under Open recent, using the same pull request indicators as the workspace sidebar. Archived and deleted workspaces drop out of the list.
  • Files you attach to chat are saved to the workspace Canvas and appear in the Canvas tab. Open the paperclip menu and choose Attach folder to attach a directory while preserving its relative paths. Each folder selection is limited to 50 files and 50MB, with a 25MB limit per file.
  • Pending Learning proposals appear at the end of chat history. Click a proposal to review or edit its details, then approve, reject, or withdraw it.
  • The full-height 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. Toggle it open or closed with the pane button beside Info in the workspace header. In All Changes, mark files as viewed to collapse them; reviewed state persists locally and clears when the file’s diff changes. File paths mentioned in agent messages open in Canvas for canvas files or the provenance pane for repo files. Changed-file pills open the exact diff from that turn; other repository file pills open a full-file preview. PNG, JPEG, GIF, WebP, and SVG files up to 5MB open as inline previews; larger images show a size warning instead. When inspecting markdown, choose Raw for the source or Formatted for the Streamdown-rendered document; changed markdown files also retain the Diff view.
  • Media appears as a folder in Canvas. Expand it and select an image, video, audio file, or document to open it in the main workspace tab bar.
  • The Subagents tab sits beside Canvas and Terminal at the bottom of the Provenance Pane. Agent plan checklists appear in chat as they are updated. The tab groups child agents under the workspace chat that created them and preserves nested child-agent relationships. Codex subagent activity appears here while internal collaboration waits stay out of chat history. Click a child agent to open its history in the main workspace tab bar; close that tab to return to the parent chat. Follow-up messages identify the contacted subagent and show its provider in chat history.
  • 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.
  • The Owner filter surfaces workspaces that aren’t your own when an admin enables Workspace Visibility in Organization → Settings → Preferences. Pick specific teammates or All to browse every team workspace.
  • 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.
  • Environment folder order: Drag environment folders to reorder them. The custom order syncs across your signed-in devices, while Pinned remains fixed at the top.
  • Compact workspace rows: Workspaces render as single rows (optional pull request indicator, name, archive, and the actions menu) indented under their environment. Rows without linked pull requests leave the indicator slot empty so names stay aligned; lifecycle status icons aren’t shown. 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.
  • Split view: On desktop, choose Open in split view from a non-selected workspace’s actions menu or drag its sidebar row into the workspace area. Both workspaces appear in resizable side-by-side panes and as a paired sidebar row. Multiple pairs can remain in the sidebar: pairs from one environment stay in that folder, while cross-folder pairs appear under Pinned. Selecting either member opens its pair. Choose Close split view or drag either member back into the sidebar list to remove that pairing. The pair closes automatically if either workspace is archived or disappears from the sidebar. A workspace can belong to only one pair, and creating a new pair detaches its members from older pairs. Split pairings and pane sizes persist across reloads in the same browser; split view is ignored on mobile.
  • Unread replies: A green dot marks a workspace whose latest agent turn finished after you last opened it. Opening the workspace clears the indicator across web, desktop, and mobile.
  • Pull request indicators: Workspace rows show green for open pull requests, purple for merged, and red for closed. Counts identify multiple pull requests in one state, while proportionally colored icons make mixed states easy to scan.
  • Workspace notes: Choose Add Note or Edit Note from a workspace’s actions menu. Notes sync across your signed-in devices, are scoped to the current organization and user, and appear in the workspace hover preview.
  • 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, preferences, and custom order sync across your signed-in devices. Dragging a workspace switches to custom order; choosing another sort clears that custom order.
  • Cross-device sync: Replicas caches this interface state on each device so it appears immediately. After loading, the app refreshes it from your account and reconciles any differences; changes update both the local cache and the synced copy.
  • Global search (Cmd/Ctrl+K): jump to dashboard pages, environments, automations, and workspaces across every available scope, including archived workspaces that are not loaded in the sidebar. You can also open archived workspaces, view keyboard shortcuts, send feedback, contact Replicas, or open the documentation.
  • Trigger Rebase on the default branch or Merge in the default branch from the workspace card’s actions menu (the ⋯ button, under Sync with the default branch). The selected option uses each repository’s configured default branch and is sent as a message to the active agent chat.

​
Chat commands

On the dashboard landing page, type / in the What would you like to build composer to open slash-command autocomplete for the selected agent. Click a command or use the arrow keys and Enter or Tab to select it. Drag and drop supported images onto the composer to attach them before creating a workspace. Mode commands such as /plan, /goal, and /fast apply before Replicas creates the workspace in the selected environment. The composer accepts /compact on Claude and Codex chats, which invokes each agent’s native in-session compaction without starting a new session. 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. Force sleep: Put an awake workspace to sleep on demand from the sidebar actions menu (⋯ → Force sleep) to stop compute immediately instead of waiting for auto-sleep. It wakes again on the next interaction. 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 and stay paused; select Restore from the sidebar or workspace chat composer to make one active again. 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 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 and the Changes view, including repository diffs, are also available without waking. See Data Retention.

​
Troubleshooting

“Workspace is under heavy load”: When the health probe fails and sandbox metrics show memory or CPU pegged, the banner reports that the workspace is under heavy load, with the live memory and CPU percentages. This means agent tasks (large builds, analyzers, test suites) are consuming the workspace’s resources and temporarily starving the engine, not an infrastructure fault. Workspaces provision swap and shield the engine from the out-of-memory killer, so these tasks slow the workspace down rather than making it unreachable; the banner clears on its own once the tasks finish. If it persists, the heavy task may be stuck; open a terminal and stop it. “Workspace engine is temporarily unavailable / Engine health check failed (…)”: Replicas pings the workspace’s engine before showing live state. If the probe fails and the workspace is not under heavy load, the banner appears with the underlying reason in parentheses: 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. Wake/resume failures also surface here, with a Try again button. 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). Trial organizations can have up to 50 manual workspaces running or preparing at a time; metered API and Automation workspaces do not consume those slots and have a separate limit of 100 running or preparing workspaces per organization on every plan. If a trial exhausts its 15,000 automated minutes, running automated workspaces are suspended (never deleted); when the trial itself ends, every running workspace is suspended until the org subscribes. See Billing for the full breakdown.