---
title: Install Carbon
description: What Carbon needs, how to download and install it, how to add an agent CLI, and what happens on first launch.
sidebar:
  order: 1
---

Carbon is a Mac app. It runs the coding agent CLIs you install yourself, so setting it up is two things: the app, and at least one agent.

## Requirements

- macOS 11 or later.
- Apple silicon or Intel. There is one universal download for both.
- At least one agent CLI: Claude Code, Codex, pi, fx or Grok Build. See [Agents](/docs/using-carbon/agents).
- git, for branches and worktrees. A folder that is not a git repository still works, without those two.
- Optional: the GitHub CLI (`gh`), signed in. Carbon uses it to list your repositories when you attach a project, and for the pull request tab.

## Download and install

1. **Download**

    On [carbonhq.sh](https://carbonhq.sh), click **Download for macOS**. You get `Carbon_universal.dmg`.

2. **Install**

    Open the dmg and drag Carbon into Applications.

3. **Open**

    Open Carbon from Applications. It is signed and notarized by Apple.

## Install an agent

Carbon installs no agent and stores no agent login. Each agent keeps its own, exactly as it does in your terminal. If an agent already works in your terminal, it works in Carbon.

You pick the agent in the composer's model picker. An agent that is not installed has a small red dot on its mark. Pick it anyway and the composer tells you:

> Codex isn't installed, so this session can't start.

Beside that line are two buttons:

- **Copy command** copies the vendor's own install command. Paste it into a terminal.
- **Install guide** opens the vendor's install page.

Carbon never runs the installer for you. These are the commands it offers:

| Agent | Install command |
|---|---|
| Claude Code | `curl -fsSL https://claude.ai/install.sh \| bash` |
| Codex | `curl -fsSL https://chatgpt.com/codex/install.sh \| sh` |
| pi | `curl -fsSL https://pi.dev/install.sh \| sh` |
| fx | `curl -fsSL https://fx.sh/setup.sh \| bash` |
| Grok Build | `curl -fsSL https://x.ai/cli/install.sh \| bash` |

Then sign in to the agent. [Agents](/docs/using-carbon/agents#signing-in) says how, and [Accounts](/docs/settings/accounts) shows who each agent runs as.

:::note
Carbon looks for each agent once and remembers the answer. If you install an agent while Carbon is running, it still reads as missing. Quit with **Quit completely** (see below) and open Carbon again, so the background process looks again.
:::

## First launch

Carbon opens on a new task: a composer in the middle of the window, and the sidebar on the left. [Your first session](/docs/get-started/first-session) walks through the rest.

{/* screenshot: the empty window on first launch, composer centered, sidebar with New Task and Issues */}

### Carbon keeps running after you quit

Your sessions run in a background process, not in the window. Close the window or quit the app and the agents keep working. Open Carbon again and you find them where you left them.

When you quit (`⌘Q`, or the window's close button), Carbon asks first:

- **Quit** closes the app. Sessions keep running in the background.
- **Quit completely** closes the app and stops every session too.
- **Cancel** keeps Carbon open.

### The browser downloads in the background

Carbon has a built-in browser, and it runs on Chromium. Chromium is not in the download, since it is a few hundred megabytes. A few seconds after the window first opens, Carbon fetches it in the background. There is nothing to click.

You can see how far it has got in Settings → Integrations → **Browser**, and on the browser tab while it is still downloading. If the download fails, Carbon tries again; you can also press **Retry** there. **Remove** deletes it; it comes back the next time Carbon starts.

## The `carbon` command line

`carbon` is a separate command line tool. It lets your agents start sessions of their own, message other sessions and drive the browser. Carbon tells its agents how to install it when they need it. See [carbon CLI](/docs/cli).

## Limits

- Mac only. Carbon can also run on a Linux server that you drive from the Mac app: see [Connect a server](/docs/server).
- Carbon does not install an agent or sign you in to one. Each agent uses its own login, subscription or key.