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

# Replicas

> Launch background coding agents in cloud workspaces

Replicas runs coding agents in cloud workspaces built from an environment — a config bundle that carries the repository binding plus the variables, files, skills and MCPs the agent gets. The Cargo integration lets a workflow launch an agent and use whatever it produced (branches, pull requests) in downstream nodes.

## Authentication

Connect to Replicas using an API key created from the Replicas dashboard under **Organization → Settings → API Keys**.

### Connection details

| Field       | Description           |
| ----------- | --------------------- |
| **API Key** | Your Replicas API key |

***

## Replicas actions

### Launch agent

Create a workspace and send an initial message to a coding agent.

**Configuration**

| Field              | Description                                                                       |
| ------------------ | --------------------------------------------------------------------------------- |
| **Environment**    | The Replicas environment the workspace is created from                            |
| **Prompt**         | The initial message sent to the coding agent                                      |
| **Workspace name** | Name of the workspace — whitespace is replaced with dashes                        |
| **Coding agent**   | Claude Code, Codex, Cursor, Opencode or Pi                                        |
| **Model**          | Model identifier for the selected coding agent                                    |
| **Thinking level** | How much reasoning effort the agent puts in                                       |
| **Plan mode**      | Have the agent propose a plan instead of editing code                             |
| **Compute size**   | Small (2 vCPU, 8 GB) or Large (4 vCPU, 16 GB)                                     |
| **Lifecycle**      | Whether the workspace keeps running, sleeps or is archived once the agent is done |

The **Environment** dropdown lists the team and personal environments in your Replicas
organization. The Global environment is not listed: it only layers configuration onto the
other environments and has no repository binding, so it cannot back a workspace.

Leave **Workspace name** empty to get a name derived from the workflow node and the record
being processed.

**Waiting for the agent**

The node stays pending until Replicas calls back, so downstream nodes run against a
finished agent rather than a workspace that has only just started. Replicas notifies Cargo
directly — nothing is polled — and the node resumes on the `replica.turn_completed`
callback. A `replica.error` callback fails the node with the reason Replicas reported.

**Output**

| Field             | Description                                                 |
| ----------------- | ----------------------------------------------------------- |
| `id`              | Workspace identifier                                        |
| `name`            | Workspace name                                              |
| `status`          | Workspace status when the turn finished                     |
| `url`             | Link to the workspace in the Replicas dashboard             |
| `branches`        | Branch, default branch and pull request URLs per repository |
| `pullRequestUrls` | Every pull request URL the agent opened during the turn     |

***

## Use cases

<AccordionGroup>
  <Accordion title="Automated code changes" icon="code-branch">
    Turn a qualified request into a branch and a pull request without a human in the loop.
  </Accordion>

  <Accordion title="Codebase research" icon="magnifying-glass">
    Ask an agent to investigate a repository and feed its findings into the rest of the workflow.
  </Accordion>

  <Accordion title="Triage at scale" icon="list-check">
    Launch one agent per incoming issue and collect the pull requests they open.
  </Accordion>

  <Accordion title="Scheduled maintenance" icon="clock">
    Run dependency bumps or migrations on a schedule and review the resulting pull requests.
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Give the agent a complete prompt** - It cannot ask follow-up questions mid-run
2. **Pick the environment carefully** - It decides which repository the agent works on
3. **Use plan mode to review first** - Have the agent propose an approach before it writes code
4. **Sleep or archive when done** - Workspaces bill per minute while they stay up