Config Reference

Beige is configured with a single ~/.beige/config.json5 file. JSON5 is JSON with comments, trailing commas, and unquoted keys. You can also override the path with --config.

Environment Variables

Any string value can reference environment variables using ${VAR_NAME}. Variables are resolved at startup — if a referenced variable is not set and has no default, the gateway exits with an error.

apiKey: "${ANTHROPIC_API_KEY}",            // resolved from env at startup
apiKey: "${ANTHROPIC_API_KEY:-fallback}",  // uses "fallback" if env var is not set

The ${VAR_NAME:-default} syntax provides a fallback value when the variable is not set. Without a default, missing variables cause a startup error.

Plugin Path Resolution

Plugin path values are resolved relative to the config file’s directory, unless they are absolute paths. Installed plugins (via beige plugins install) are auto-resolved.

Full Config Reference

{
  // ── LLM Providers ────────────────────────────────────────────────────
  llm: {
    providers: {
      anthropic: {
        apiKey: "${ANTHROPIC_API_KEY}",
      },
      openai: {
        apiKey: "${OPENAI_API_KEY}",
      },
      google: {
        apiKey: "${GOOGLE_API_KEY}",
      },
      // Custom / OpenAI-compatible providers
      zai: {
        apiKey: "${ZAI_API_KEY}",
        baseUrl: "https://api.zai.com/v1",
        api: "openai-completions",
      },
      // Local (no apiKey needed)
      ollama: {
        baseUrl: "http://localhost:11434/v1",
        api: "openai-completions",
      },
    },
  },

  // ── Plugins ──────────────────────────────────────────────────────────
  // Plugins provide tools, channels, hooks, and skills.
  // Plugins installed via `beige plugins install` are added here automatically.
  plugins: {
    // Plugin with custom config (path auto-resolved if installed)
    github: {
      config: { allowedCommands: ["repo", "issue", "pr"] },
    },
    // Local plugin (path required)
    git: {
      path: "~/.beige/plugins/git",
      config: {},
    },
    // Channel plugin
    telegram: {
      config: {
        token: "${TELEGRAM_BOT_TOKEN}",
        allowedUsers: [123456789],
        agentMapping: { default: "assistant" },
        defaults: { verbose: false, streaming: true },
      },
    },
  },

  // ── Skills ────────────────────────────────────────────────────────────
  // Standalone skill packages (plugins can also register skills).
  skills: {
    "code-review": {
      path: "./skills/code-review",
    },
  },

  // ── Agents ───────────────────────────────────────────────────────────
  agents: {
    assistant: {
      model: {
        provider: "anthropic",
        model: "claude-sonnet-4-6",
        thinkingLevel: "off",
        // Trigger auto-compaction at 100k tokens instead of the default (~184k)
        compactionThreshold: 100000,
      },
      fallbackModels: [
        {
          provider: "anthropic",
          model: "claude-3-5-sonnet-20241022",
          compactionThreshold: 80000,  // per-fallback threshold
        },
      ],
      tools: ["git", "github"],
      skills: ["code-review"],
      pluginConfigs: {
        git: {
          denyCommands: ["del"],
        },
      },
      sandbox: {
        image: "beige-sandbox:latest",
        // Hard memory cap — container gets OOM-killed before it can exhaust host RAM.
        // Default is "3g". Use a lower value on memory-constrained hosts (e.g. Raspberry Pi).
        memoryLimit: "3g",
        extraMounts: {
          "/host/path": "/container/path",
        },
        extraEnv: {
          "NODE_ENV": "production",
        },
      },
    },
  },

  // ── Gateway ───────────────────────────────────────────────────────────
  gateway: {
    host: "127.0.0.1",
    port: 7433,
    logFile: "~/.beige/logs/gateway.log",
  },
}

Field Reference

`llm.providers.<name>`

Field	Required	Description
`apiKey`	Yes*	API key — use `${VAR}` for env var. Not required for local providers.
`baseUrl`	No	Custom API endpoint. Required for non-built-in providers.
`api`	No	API type (see below). Auto-set for built-in providers.

API types:

Value	Use for
`anthropic-messages`	Anthropic Claude (default for `anthropic`)
`openai-completions`	OpenAI, ZAI, Groq, Ollama, and most OpenAI-compatible APIs
`openai-responses`	OpenAI Responses API
`google-generative-ai`	Google Gemini (default for `google`)

`plugins.<name>`

Field	Required	Description
`path`	No	Path to the plugin package directory. Auto-resolved for installed plugins.
`config`	No	Arbitrary object passed to `createPlugin(config, ctx)`

`skills.<name>`

Field	Required	Description
`path`	Yes	Path to the skill package directory

`agents.<name>.model`

Field	Required	Description
`provider`	Yes	Must match a key in `llm.providers`
`model`	Yes	Model ID as the provider expects it
`thinkingLevel`	No	`off` \| `minimal` \| `low` \| `medium` \| `high` — extended thinking budget
`compactionThreshold`	No	Token count at which auto-compaction triggers for this model. Must be less than the model’s context window. Defaults to `contextWindow − 16384`. Example: `100000` on a 200k model compacts at 100k tokens.

`agents.<name>.fallbackModels`

Optional array of ModelRef objects tried in order when the primary model fails or is rate-limited. Each fallback can carry its own thinkingLevel and compactionThreshold. The gateway uses a multi-pass retry loop: it cycles through the model list up to 3 times, giving each model up to 3 chances per prompt. Rate-limited models (HTTP 429) are skipped immediately; transient errors (e.g. “overloaded”) consume one of the 3 chances and the model is retried on the next pass. See Model Fallback for details.

`agents.<name>.sandbox`

Field	Required	Default	Description
`image`	No	`"beige-sandbox:latest"`	Docker image name
`memoryLimit`	No	`"3g"`	Hard memory cap for the container (e.g. `"3g"`, `"512m"`). The container is OOM-killed by the cgroup before it can exhaust host RAM. Swap is also capped to the same value, so the limit is always hard.
`extraMounts`	No	—	`{ "/host/path": "/container/path" }` — reduces isolation
`extraEnv`	No	—	`{ "KEY": "value" }` — visible to the agent, never use for secrets

Why memoryLimit matters on constrained hosts. When the Docker host has no per-container memory limit and cgroup_disable=memory is set in the kernel (common on Raspberry Pi), a runaway process inside the sandbox — multiple concurrent npm install runs, for example — can exhaust all available RAM. The kernel never gets to invoke the OOM killer, and a hardware watchdog fires a hard reboot instead. Setting memoryLimit gives the container a cgroup ceiling so Docker’s OOM killer terminates the offending process inside the container, leaving the rest of the system intact.

`agents.<name>.workspaceDir`

Optional. Absolute or relative path for the agent’s workspace directory.

Default: ~/.beige/agents/<agentName>/workspace/
Inside sandbox: Always mounted at /workspace

`agents.<name>.pluginConfigs`

Optional. Per-agent plugin config overrides. Each key must reference a plugin in config.plugins. Values are deep-merged with the top-level plugins.<name>.config.

Arrays are replaced, not merged. The deep-merge recursively merges nested objects, but arrays and primitives from the agent override replace the base value entirely.

`gateway`

Field	Default	Description
`host`	`"127.0.0.1"`	HTTP API bind address
`port`	`7433`	HTTP API port
`logFile`	`~/.beige/logs/gateway.log`	Daemon stdout/stderr log file

Validation at Startup

Check	Error if
`llm.providers` exists	Missing or empty
`agents` exists	Missing or empty
Each agent has `model.provider` + `model.model`	Missing model config
Agent’s `pluginConfigs` keys exist in `plugins`	Unknown plugin in `pluginConfigs`
Agent’s tools resolve to registered plugin tools	Unknown tool (checked after plugin loading)
Agent’s skills exist in `skills` or plugin-registered	Unknown skill
All `${VAR}` references resolve	Environment variable not set

Minimal Working Config

{
  llm: {
    providers: {
      anthropic: { apiKey: "${ANTHROPIC_API_KEY}" },
    },
  },
  agents: {
    bot: {
      model: { provider: "anthropic", model: "claude-sonnet-4-6" },
      tools: [],
    },
  },
}

This agent has no plugins but can still use the 4 core tools (read, write, patch, exec) inside its sandbox.

Host Directory Structure

~/.beige/
├── config.json5                   # main config file
├── agents/
│   └── <agent>/
│       ├── workspace/             # mounted as /workspace (rw) in sandbox
│       └── launchers/             # generated launcher scripts → /tools/bin (ro)
├── sessions/
│   ├── session-map.json           # maps session keys → .jsonl file paths
│   ├── session-settings.json      # per-session setting overrides
│   └── <agent>/
│       └── <id>.jsonl             # pi conversation session files
├── sockets/
│   └── <agent>.sock               # Unix socket per agent
├── plugins/                       # installed plugin files
│   ├── github/

│   └── git/
├── packages/                      # intact multi-plugin packages
│   └── matthias-hausberger-beige-toolkit/
├── data/
│   ├── plugin-data.json
│   └── provider-health.json
└── logs/
    ├── audit.jsonl                # append-only audit log
    └── gateway.log                # daemon stdout/stderr

​Environment Variables

​Plugin Path Resolution

​Full Config Reference

​Field Reference

​llm.providers.<name>

​plugins.<name>

​skills.<name>

​agents.<name>.model

​agents.<name>.fallbackModels

​agents.<name>.sandbox

​agents.<name>.workspaceDir

​agents.<name>.pluginConfigs

​gateway

​Validation at Startup

​Minimal Working Config

​Host Directory Structure

Environment Variables

Plugin Path Resolution

Full Config Reference

Field Reference

`llm.providers.<name>`

`plugins.<name>`

`skills.<name>`

`agents.<name>.model`

`agents.<name>.fallbackModels`

`agents.<name>.sandbox`

`agents.<name>.workspaceDir`

`agents.<name>.pluginConfigs`

`gateway`

Validation at Startup

Minimal Working Config

Host Directory Structure