> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryreplicas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 six 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                                                                                                                                                                                                                                                                       |
| **Archived**     | Paused for retention, no charges accrue                                                                                                                                                                                                                                                         |
| **Failed**       | Setup/provisioning failed, a wake/resume attempt failed, or the underlying sandbox died. Failures show a **Try again** button that clears the error and re-attempts wake. If retry does not recover the workspace, reach out to [founders@replicas.dev](mailto: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](/features/coding-agents/claude-code), [Codex](/features/coding-agents/codex), [Cursor](/features/coding-agents/cursor), [Opencode](/features/coding-agents/opencode), and [Pi](/features/coding-agents/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 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, 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:

```bash theme={null}
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](/features/workspaces/repository-configuration) in `replicas.json` or `replicas.yaml`:

```yaml replicas.yaml theme={null}
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`](/features/cli#computer-use) 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.

### Terminal tab

Open **Terminal** beside **Canvas**, **Media**, 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` + `/`.

| Shortcut                    | Action              |
| --------------------------- | ------------------- |
| `Cmd` + `K`                 | Search              |
| `Cmd` + `B`                 | Toggle the sidebar  |
| `Cmd` + `Shift` + `↑` / `↓` | Switch workspaces   |
| `Cmd` + `Shift` + `←` / `→` | Switch chat tabs    |
| `Cmd` + `Shift` + `M`       | Toggle Plan / Build |

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

* When a workspace has one open GitHub pull request and CI passes without conflicts, **Merge** appears on the left side of the workspace header's PR control (under the actions menu on mobile). After confirmation, the workspace engine runs GitHub CLI with the configured credential without consuming an agent turn. Required reviews, branch protection, conflicts, and permissions still apply. The action is unavailable when the organization enables [PR merge blocking](/features/github#pr-merge-blocking). With [PR attribution](/features/github#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**. Archived and deleted workspaces drop out of the list.
* Files you attach to chat are saved to the workspace [Canvas](/features/workspaces/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 5MB limit per file.
* Pending [Learning proposals](/features/learnings#human-approval-workflow) 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 in the top-right corner, which stays in place whether the pane is open or closed. 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](/features/workspaces/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.
* **Media** sits beside **Canvas** in the artifact pane. Select an image, video, audio file, or document to open it in the main workspace tab bar.
* The **Subagents** tab sits beside **Canvas**, **Media**, 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.
* **Team Workspaces** view surfaces workspaces that aren't your own, with a "team" badge and creator tooltip, when an admin enables Workspace Visibility in Organization → Settings → Preferences. 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.
* **Environment folder order**: Drag environment folders to reorder them. The custom order is saved locally per organization and user, while **Pinned** remains fixed at the top.
* **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.
* **Workspace notes**: Choose **Add Note** or **Edit Note** from a workspace's actions menu. Notes are saved only in the current browser, 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 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 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`](/features/workspaces/plan-mode), `/goal`, and [`/fast`](/features/workspaces/fast-mode) 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](/features/workspaces/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](/features/environments) for the full model and how to create one. Open [Environments](https://tryreplicas.com/dashboard/environment) 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](/features/environments#warm-hooks) 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](/admin/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:

| 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 [founders@replicas.dev](mailto: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](mailto: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 orgs that exhaust their 15,000 automated minutes have running automated workspaces suspended (never deleted); when the trial itself ends, every running workspace is suspended until the org subscribes. See [Billing](/admin/billing) for the full breakdown.