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

# Installation

> Install Beige, run your first agent, and understand the minimal config

## Prerequisites

* Node.js 22+
* Docker

## Quick Start

Get Beige running in under 5 minutes.

### Step 1 — Install

```bash theme={null}
npm install -g @matthias-hausberger/beige
```

### Step 2 — Run setup

```bash theme={null}
beige setup
```

This creates `~/.beige/config.json5` with a minimal default configuration.

### Step 3 — Add your API key

Open `~/.beige/config.json5` and set your Anthropic API key:

```json5 theme={null}
{
  // ...
  llm: {
    providers: {
      anthropic: {
        apiKey: "sk-ant-...",  // paste your key here, or use ${ANTHROPIC_API_KEY}
      },
    },
  },
  // ...
}
```

Alternatively, keep the default `${ANTHROPIC_API_KEY}` and export it in your shell:

```bash theme={null}
export ANTHROPIC_API_KEY="sk-ant-..."
```

Of course you can also use other provides, see [LLM Providers](/agents/providers).

### Step 4 — Start the gateway

```bash theme={null}
beige gateway start
```

### Step 5 — Start the TUI

```bash theme={null}
beige tui
```

That's it. The gateway builds the sandbox Docker image automatically on first start.

***

## What `beige setup` Creates

`beige setup` initializes `~/.beige/`:

```text theme={null}
~/.beige/
├── config.json5          # your config (edit this)
└── plugins/              # installed plugins go here
```

Setup is **idempotent** — it only creates files that do not already exist. Re-running it after partial failures is always safe.

***

## Default Config

The generated `~/.beige/config.json5`:

```json5 theme={null}
{
  $schema: "https://raw.githubusercontent.com/matthias-hausberger/beige/main/config.schema.json",

  llm: {
    providers: {
      anthropic: {
        apiKey: "${ANTHROPIC_API_KEY}",
      },
    },
  },

  agents: {
    beige: {
      model: {
        provider: "anthropic",
        model: "claude-sonnet-4-6",
        thinkingLevel: "off",
      },
      tools: [],
      sandbox: {
        image: "beige-sandbox:latest",
      },
    },
  },
}
```

This agent has no plugins but can use the 4 core tools (read, write, patch, exec). Install plugins to add more capabilities:

```bash theme={null}
beige plugins install npm:@matthias-hausberger/beige-toolkit
```

For the full config reference, see [Configuration](/agents/configuration).

***

## Updating

```bash theme={null}
npm install -g @matthias-hausberger/beige
```

Setup is not re-run automatically on update. Existing files are never overwritten.

***

## Uninstalling

```bash theme={null}
npm uninstall -g @matthias-hausberger/beige
```

`~/.beige/` is **not** removed — it holds your config, sessions, audit logs, and plugin data. Remove it manually if you want a clean slate:

```bash theme={null}
rm -rf ~/.beige
```

***

## Source Install (Contributing)

If you are contributing to Beige or want to run from source:

```bash theme={null}
git clone https://github.com/matthias-hausberger/beige.git
cd beige
pnpm install
```

`pnpm run beige` automatically sets `BEIGE_HOME=./.beige`, so all runtime data (config, sessions, logs, sockets) stays inside the repo folder — completely separate from your global `~/.beige`. The `.beige/` folder is already in `.gitignore`.

Everything works identically to the global install:

```bash theme={null}
pnpm run beige setup                        # creates ./.beige/config.json5
export ANTHROPIC_API_KEY="sk-ant-..."

pnpm run beige gateway start --foreground   # Shell 1
pnpm run beige tui                          # Shell 2
```

You can also point `BEIGE_HOME` at any directory:

```bash theme={null}
BEIGE_HOME=/tmp/my-beige beige gateway start
```