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

npm install -g @matthias-hausberger/beige

Step 2 — Run setup

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:

{
  // ...
  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:

export ANTHROPIC_API_KEY="sk-ant-..."

Of course you can also use other provides, see LLM Providers.

Step 4 — Start the gateway

beige gateway start

Step 5 — Start the TUI

beige tui

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

---

What beige setup Creates

beige setup initializes ~/.beige/:

~/.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:

{
  $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:

beige plugins install npm:@matthias-hausberger/beige-toolkit

For the full config reference, see Configuration.

---

Updating

npm install -g @matthias-hausberger/beige

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

---

Uninstalling

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:

rm -rf ~/.beige

---

Source Install (Contributing)

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

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:

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:

BEIGE_HOME=/tmp/my-beige beige gateway start