> ## 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

> Understand workspace setup, tools, collaboration, and lifecycle.

A workspace is an isolated virtual machine with your repositories, environment configuration, and chosen coding agent. Create one from the app or trigger one through an integration, automation, CLI command, or API request.

## How workspaces run

Each workspace runs the Replicas Engine, which manages agent sessions, queued messages, git operations, previews, and workspace tools. The engine keeps the agent session and branch available while the workspace is awake.

Messages sent while an agent is busy are queued in order. You can edit or remove a queued message before it starts. Supported agents also let you steer an active turn with a queued message.

### Background tasks

Claude background tasks appear in the transcript with their status, latest activity, output path, and resource usage. They can continue after the turn that created them. **Stop** cancels the active turn and its background tasks.

Workspace lifecycle actions such as **Archive when done** wait for background work to finish.

## Workspace tools

### Changes and files

Use the provenance pane to review changed files, browse the repository, and open files mentioned by the agent. In **Changes**, you can mark files as viewed and attach line comments to send with your next message.

Files attached to chat and files the agent places in `~/.replicas/canvas/` appear in [Canvas](/features/workspaces/canvas). Images, video, audio, PDFs, Markdown, Mermaid, HTML, and common text formats have inline viewers.

Click an image attached to a user message to inspect it at full size.

### Desktop tab

Every workspace includes a Linux desktop with Chrome. Open **Desktop** in the provenance pane to watch the screen, then select **Interact** for mouse, keyboard, scrolling, and audio.

The desktop and its processes continue running when you close the viewer. They also survive sleep on the default pause mode. Only authenticated Replicas users can open its viewer URL.

Use the [CLI computer commands](/features/cli#computer-use) when an agent needs to capture screenshots, interact with the browser, or record the screen.

### Terminal and Docker

Open **Terminal** beside Canvas to run an interactive shell. Use **+** to create independent terminal sessions.

Docker is installed but starts on demand. To make it available during every workspace setup, add this command to a [start hook](/features/workspaces/repository-configuration):

```yaml replicas.yaml theme={null}
startHook:
  commands:
    - sudo service docker start && until docker info >/dev/null 2>&1; do sleep 0.2; done
```

## Chats and collaboration

* Create multiple chats to separate workstreams. Each chat keeps its own agent, model, effort, and history.
* Drag chat tabs to reorder them. Delete a chat from its context menu; deleting an active chat stops its turn.
* Long chats open at the newest messages and load older history as you scroll.
* Share workspaces with teammates to add them to the teammate's **Shared** view. Organization members already have access to the workspace.
* Use split view on desktop to compare multiple workspaces side by side.
* The workspace header shows linked pull requests and their checks. Eligible reviewers can approve, and standalone mergeable pull requests can be merged from the checks popover even while the workspace is sleeping. Merging uses the GitHub integration directly and does not wake the workspace.
* Use `Cmd`/`Ctrl` + `K` to search pages, environments, automations, and workspaces. Press `Cmd`/`Ctrl` + `/` for the full keyboard shortcut reference.

### Chat commands

Type `/` in the composer to see commands supported by the selected agent. The menu also opens on a `/` typed after existing text, and closes once you type a space. Picking a command replaces only the `/` word you are typing, leaving the rest of your draft untouched.

* `/plan` asks the agent to propose a plan before editing. See [Plan mode](/features/workspaces/plan-mode).
* `/fast` enables a faster service tier where supported. See [Fast mode](/features/workspaces/fast-mode).
* `/compact` compacts the active Claude Code or Codex session.
* `/goal <objective>` creates a persistent goal for a Codex chat.

## Repository targeting

A workspace can use one repository or a repository set. Repository sets save combinations of repositories for tasks that span services.

Every workspace uses one [environment](/features/environments). The environment provides its repositories, variables, files, skills, MCP servers, system prompt, and setup hooks. Values from the organization-wide **Global** environment are merged into it.

Before creating a task from Home, the **starting point** control sets the branch each repository starts on. A single-repository environment opens its branch list directly; otherwise every repository is listed so you can choose a branch for each. Repositories without an override use their [configured default branch](/features/github#default-branch).

## Sleep and wake

| State         | Meaning                                                          |
| ------------- | ---------------------------------------------------------------- |
| **Booting**   | The VM is starting and applying setup.                           |
| **Preparing** | A new or sleeping workspace is becoming ready.                   |
| **Awake**     | The workspace can process messages.                              |
| **Sleeping**  | Compute is paused and no workspace charges accrue.               |
| **Archived**  | The workspace is hidden from the active list and remains paused. |
| **Failed**    | Setup or wake failed and can be retried.                         |

Workspaces sleep after one hour without activity. Sending a message wakes a sleeping or archived workspace automatically and resumes its previous branch and agent session.

Sleeping workspaces with no activity for seven days are archived. Archived workspaces with no activity for 30 days are deleted. Opening, waking, or messaging a workspace resets its activity window. See [Data retention](/admin/data-retention) for organization controls.

You can force sleep, archive, restore, or permanently delete a workspace from its sidebar actions menu. These actions are also available in bulk-selection mode.

## Troubleshooting

### Workspace under heavy load

The workspace is using enough CPU or memory to delay its engine. Wait for the active build or analysis to finish, or open a terminal and stop a stuck process. The banner clears when resource use falls.

### Engine temporarily unavailable

Reload after a few seconds. The workspace state on disk is unaffected by a transient engine health-check failure. If the workspace remains unavailable, select **Try again** when offered or contact [founders@replicas.dev](mailto:founders@replicas.dev).

### Setup or wake failed

Select **Try again** to repeat setup or wake. Repository authentication and setup-command failures remain visible in the workspace so you can correct the underlying configuration.

## Billing

Workspace compute is billed only while active. Manual workspaces on paid plans are covered by the seat subscription; API and automation workspaces are metered by size. See [Billing](/admin/billing) for current limits and rates.