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

# Quickstart

> Set up Replicas and create your first workspace in 5 minutes.

<video src="https://mxeqiomwgdgaesecwtct.supabase.co/storage/v1/object/sign/docs-assets/linear-flow.mp4?token=eyJraWQiOiJzdG9yYWdlLXVybC1zaWduaW5nLWtleV8yMzJlY2QyZC1lNzc1LTQxM2MtYTBlMC05ZmU4YzIwMzM3NWEiLCJhbGciOiJIUzI1NiJ9.eyJ1cmwiOiJkb2NzLWFzc2V0cy9saW5lYXItZmxvdy5tcDQiLCJpYXQiOjE3NjU1NzA1NjEsImV4cCI6MTgyODY0MjU2MX0.xDyBelsdugCKVtMJLTBP1yI4x7sPPuAmz8OM5OtRRJU" controls />

## Prerequisites

* [Replicas](https://tryreplicas.com) account
* GitHub or GitLab account with repository access
* At least one of:
  * [Claude Code](https://claude.ai/download) subscription, Anthropic API key, or AWS Bedrock credentials
  * [Codex](https://openai.com/codex/) subscription
  * Cursor API key
  * OpenCode Go subscription, Aster API key, or OpenRouter API key

Replicas names your organization from the company domain in a work signup email. For a personal email, it uses your Google profile or a name inferred from the address, such as **Jane Doe's Organization**; without a usable name it keeps **My Organization**. Admins can rename the organization anytime in [Organization → Settings](https://tryreplicas.com/dashboard/settings).

***

## Step 1: Connect Source Control

Connect GitHub or GitLab and add at least one repository or project for Replicas to work on.

1. Go to the [dashboard](https://tryreplicas.com/dashboard). The onboarding guide will open automatically
2. Choose **GitHub** or **GitLab** in **Connect Source Control**
3. Authorize your account and select the repositories or projects you want to use
4. Search and select a repository or project to add

<Tip>
  You can manage repositories later in [Organization →
  Integrations](https://tryreplicas.com/dashboard/integrations). When
  you add a repository, Replicas auto-creates a default
  [environment](/features/environments) bound to it; pick that environment when
  creating a workspace. If you work across several repositories, create a
  **Repository Set** and bind an environment to that set instead.
</Tip>

***

## Step 2: Connect a Coding Agent

Replicas uses your own Claude Code subscription, Anthropic API key, Codex subscription, Cursor API key, OpenCode Go subscription, Aster API key, or OpenRouter API key to power workspaces. You need to connect at least one.

### Option A: Bring Your Subscription (CLI)

First, install the [Replicas CLI](/features/cli):

```bash theme={null}
curl -fsSL https://tryreplicas.com/install.sh | bash
replicas login
```

Then authenticate with your coding agent:

```bash theme={null}
replicas claude-auth   # For Claude Code
replicas codex-auth    # For Codex
```

This opens a browser to authenticate with your existing subscription, and saves it to your personal account. Admins setting up a subscription for the whole team should add `--org` instead.

See the [Claude Code guide](/features/coding-agents/claude-code) and [Codex guide](/features/coding-agents/codex) for agent-specific features and usage.

### Option B: Anthropic API Key

If you prefer to use a direct Anthropic API key for Claude, enter it in the onboarding guide or in [Organization → Coding Agents](https://tryreplicas.com/dashboard/agents).

Keys start with `sk-ant-`.

### Option C: AWS Bedrock

If you prefer to use Claude via AWS Bedrock, enter your AWS credentials directly in the onboarding guide or in [Organization → Coding Agents](https://tryreplicas.com/dashboard/agents):

* AWS Access Key ID
* AWS Secret Access Key
* AWS Region (e.g., `us-east-1`)

### Option D: Cursor API Key

If you prefer Cursor, enter your Cursor API key in the onboarding guide or in [Organization → Coding Agents](https://tryreplicas.com/dashboard/agents). Generate a key from [Cursor Dashboard → Integrations](https://cursor.com/dashboard/integrations).

See the [Cursor agent guide](/features/coding-agents/cursor) and [credentials](/admin/credentials) for more details.

### Option E: OpenCode Go Subscription

If you prefer Opencode with a subscription, click **Connect OpenCode Go** in the onboarding guide or in [Organization → Coding Agents](https://tryreplicas.com/dashboard/agents) and paste your OpenCode Zen API key.

### Option F: Aster API Key

To use Aster inference with Opencode or Pi, paste an Aster key under either agent in [Organization → Coding Agents](https://tryreplicas.com/dashboard/agents). The shared key starts with `sk_aster_`.

### Option G: OpenRouter API Key

If you prefer OpenRouter routing, enter the shared API key under **Opencode → OpenRouter API Key** or **Pi → OpenRouter API Key** in [Organization → Coding Agents](https://tryreplicas.com/dashboard/agents). Generate a key from the [OpenRouter keys page](https://openrouter.ai/keys).

See the [Opencode guide](/features/coding-agents/opencode), [Pi guide](/features/coding-agents/pi), and [credentials](/admin/credentials) for more details.

<Note>
  All credentials are encrypted and only accessed when provisioning workspaces.
</Note>

***

## Step 3: Create Your First Workspace

A workspace is an isolated environment where a coding agent works on your repository.

1. From the dashboard landing page, type what you'd like to build, select an
   [environment](/features/environments), and hit send to create a workspace and
   start your agent immediately
2. The compose button (pencil icon) in the sidebar brings you back to this prompt page from anywhere. To create a workspace from a dialog instead, press <kbd>⌘</kbd>/<kbd>Ctrl</kbd>+<kbd>K</kbd> and run **New workspace**
3. Start chatting with your agent

The agent can read your code, make changes, run commands, and create pull requests or merge requests, all within the sandboxed workspace.

***

## Optional: Enable Integrations

Supercharge your workflow by connecting integrations. These let you trigger Replicas from external sources instead of only through the dashboard.

### Linear

Assign Linear issues directly to Replicas like you would a team member.

1. Go to [Organization → Integrations](https://tryreplicas.com/dashboard/integrations)
2. Click **Connect Linear** and authorize your workspace
3. Assign any issue to **Replicas**. It will spin up a workspace and start working

[Learn more about Linear integration](/features/linear)

### Slack

Mention @Replicas in Slack channels to start tasks conversationally.

1. Go to [Organization → Integrations](https://tryreplicas.com/dashboard/integrations)
2. Click **Connect Slack** and authorize for your workspace
3. Invite @Replicas to channels and mention it to start a task

[Learn more about Slack integration](/features/slack)

### GitHub Triggers

Enable `@tryreplicas` mentions on GitHub issues and pull requests.

Once you've added a repository to your organization (Step 1), you can mention `@tryreplicas` on any GitHub issue or PR to trigger a workspace.

Need always-on responses for reviewer bots? In **Organization → Settings → GitHub Auto Responders**, search for bots like `greptile-apps[bot]` so Replicas reacts automatically without `@tryreplicas`.

[Learn more about GitHub integration](/features/github)

### GitLab Triggers

Enable `@tryreplicas` mentions on GitLab issues and merge requests.

Once you've connected GitLab and added a project, mention `@tryreplicas` on any GitLab issue or MR to trigger a workspace.

[Learn more about GitLab integration](/features/gitlab)

***

## Optional: Invite Team Members

Add teammates to your organization so they can create workspaces and use integrations.

1. Go to [Organization → Members](https://tryreplicas.com/dashboard/members)
2. Enter their email to send an invite
3. They'll receive an email to join your organization

***

## Customizing Workspace Setup

Create a `replicas.json` or `replicas.yaml` file in your repository root to customize how workspaces initialize:

<CodeGroup>
  ```json replicas.json theme={null}
  {
    "startHook": {
      "commands": ["npm install", "npm run build"]
    },
    "systemPrompt": "Custom instructions for agents."
  }
  ```

  ```yaml replicas.yaml theme={null}
  startHook:
    commands:
      - npm install
      - npm run build

  systemPrompt: |
    Custom instructions for agents.
    Supports multiline text.
  ```
</CodeGroup>

| Field          | Description                                |
| -------------- | ------------------------------------------ |
| `startHook`    | Commands to run when the workspace starts. |
| `systemPrompt` | Custom instructions for the coding agent.  |

[Learn more about repository configuration](/features/workspaces/repository-configuration)

***

## Where to Go Next

<CardGroup cols={2}>
  <Card title="Workspaces" icon="server" href="/features/workspaces/overview">
    How workspaces run and manage themselves
  </Card>

  <Card title="CLI" icon="terminal" href="/features/cli">
    Connect to workspaces from your terminal
  </Card>

  <Card title="Linear" icon="list-check" href="/features/linear">
    Assign tasks from Linear
  </Card>

  <Card title="GitHub" icon="github" href="/features/github">
    Trigger from GitHub issues and PRs
  </Card>

  <Card title="GitLab" icon="gitlab" href="/features/gitlab">
    Trigger from GitLab issues and MRs
  </Card>
</CardGroup>