> ## 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. # Agents > What agents are, how to configure them, and how they run An agent is a named AI assistant with its own: * **LLM session** — conversation history and model configuration * **Docker sandbox** — isolated execution environment * **Tool permissions** — the specific tools it can invoke * **Skills** — read-only knowledge packages mounted into the sandbox * **Workspace** — persistent `/workspace` directory that survives restarts Each agent is completely isolated. Agents **cannot access each other's files, sessions, or tools**. ```mermaid theme={null} graph TB subgraph "Agent: assistant" A1[LLM Session] A2[Docker Sandbox] A3["/workspace (persistent)"] A4["Tools on PATH"] A5["/skills/code-review/"] end subgraph "Agent: intern" B1[LLM Session] B2[Docker Sandbox] B3["/workspace (persistent)"] B4["Tools on PATH"] end A1 --> A2 A2 --> A3 A2 --> A4 A2 --> A5 B1 --> B2 B2 --> B3 B2 --> B4 A3 -.-x B3 A4 -.-x B4 ``` *** ## Defining an Agent Agents are defined in `config.json5` under `agents`: ```json5 theme={null} { agents: { assistant: { // LLM model (required) model: { provider: "anthropic", model: "claude-sonnet-4-6", thinkingLevel: "medium", }, // Fallback models if primary is unavailable (optional) fallbackModels: [ { provider: "anthropic", model: "claude-3-5-sonnet-20241022" }, ], // Tools this agent can use (names from plugin-registered tools) tools: ["git", "github", "slack"], // Skills this agent has access to (optional) skills: ["code-review"], // Sandbox overrides (optional) sandbox: { image: "beige-sandbox:latest", extraMounts: { "/home/user/projects": "/projects", }, extraEnv: { "NODE_ENV": "development", }, }, }, }, } ``` ### Configuration Fields | Field | Required | Description | | ---------------- | -------- | ---------------------------------------------------------- | | `model` | Yes | Provider, model ID, and thinking level | | `fallbackModels` | No | Models to try if primary fails or is rate-limited | | `tools` | No | Tool names registered by plugins (empty = core tools only) | | `skills` | No | Skill names from skills registry or plugin-registered | | `pluginConfigs` | No | Per-agent plugin config overrides (deep-merged with base) | | `sandbox` | No | Docker image, extra host mounts, extra env vars | **Model Restriction**: The `model` and `fallbackModels` together define the **only** models an agent can use. Users cannot switch to other models via the TUI or API. See [LLM Providers → Model Restriction](/agents/providers#model-restriction) for details. For the complete list of all config fields and their defaults, see the [Config Reference](/agents/configuration). *** ## Tool Permissions Tools are provided by plugins and assigned to agents by name: ```json5 theme={null} { plugins: { git: { config: { allowForcePush: false } }, github: { config: { allowedCommands: ["repo", "issue", "pr"] } }, }, agents: { // Full access assistant: { model: { provider: "anthropic", model: "claude-sonnet-4-6" }, tools: ["git", "github"], }, // Restricted — only git, no github intern: { model: { provider: "anthropic", model: "claude-sonnet-4-6" }, tools: ["git"], }, }, } ``` An agent can only use tools listed in its `tools` array. This is the deny-by-default policy. Every agent always has the 4 core tools (read, write, patch, exec) regardless of config. Plugin tools are available on the agent's `$PATH` inside the sandbox, so agents call them naturally: ```bash theme={null} exec: git status # calls the git plugin tool exec: gh issue list # calls the github plugin tool ``` See [Extensibility → Tools](/extensibility/tools) for details on how tools work. *** ## Skills Skills are read-only knowledge packages mounted into the sandbox. Unlike tools, which execute code, skills provide context and guidelines the agent reads on demand. ```json5 theme={null} { skills: { "code-review": { path: "./skills/code-review" }, }, agents: { assistant: { model: { provider: "anthropic", model: "claude-sonnet-4-6" }, tools: ["git"], skills: ["code-review"], }, }, } ``` Skills are mounted at `/skills//` in the sandbox. The system prompt references them; the agent reads the docs when relevant: ```bash theme={null} exec: cat /skills/code-review/README.md ``` See [Extensibility → Skills](/extensibility/skills) for details. *** ## Sandbox Customization ### Docker Image ```json5 theme={null} sandbox: { image: "beige-sandbox:latest", // default image built by the gateway } ``` The default image includes the Deno runtime, common utilities (curl, jq), and the tool-client binary. ### Extra Mounts Mount additional host directories into the sandbox: ```json5 theme={null} sandbox: { extraMounts: { "/home/user/projects": "/projects", "/home/user/.gitconfig": "/etc/gitconfig", }, } ``` **Warning:** Extra mounts reduce isolation. Only mount directories the agent should be able to access. ### Extra Environment Variables ```json5 theme={null} sandbox: { extraEnv: { "NODE_ENV": "development", "PROJECT_NAME": "my-app", }, } ``` **Never** put secrets in `extraEnv` — they would be visible to the agent. API keys and secrets stay on the gateway host only. *** ## Sessions Each agent's conversation history is persisted to disk as JSONL files: ``` ~/.beige/sessions/ ├── session-map.json # Maps session keys → file paths ├── session-settings.json # Per-session setting overrides └── assistant/ ├── 20260305-120000-a1b2c3.jsonl └── 20260305-143000-d4e5f6.jsonl ``` ### Session Keys | Channel | Session Key | | ----------------- | ----------------------------------------------------- | | TUI | `tui::default` | | Telegram (plugin) | `telegram:` or `telegram::` | ### Session Commands (TUI) ```bash theme={null} /new # Start a fresh session (old one preserved on disk) /beige-sessions # List saved sessions for the current agent /beige-resume 2 # Resume session #2 /beige-agent dev # Switch to a different agent ``` *** ## Multi-Agent Example ```json5 theme={null} { llm: { providers: { anthropic: { apiKey: "${ANTHROPIC_API_KEY}" }, }, }, plugins: { git: {}, github: { config: { allowedCommands: ["repo", "issue", "pr"] } }, }, skills: { "code-review": { path: "./skills/code-review" }, }, agents: { // Main assistant — full access assistant: { model: { provider: "anthropic", model: "claude-sonnet-4-6" }, tools: ["git", "github"], skills: ["code-review"], }, // Developer — code-focused with project mount dev: { model: { provider: "anthropic", model: "claude-sonnet-4-6" }, tools: ["git"], skills: ["code-review"], sandbox: { extraMounts: { "/home/user/projects": "/projects" }, }, }, // Restricted — core tools only intern: { model: { provider: "anthropic", model: "claude-sonnet-4-6" }, tools: [], }, }, } ``` *** ## Config Validation The gateway validates agent configuration 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 | | Agent's tools resolve to plugin-registered tools | Unknown tool | | Agent's skills exist in skills registry or plugin-registered | Unknown skill | | Agent's `pluginConfigs` keys exist in `plugins` | Unknown plugin | | All `${VAR}` references resolve | Environment variable not set | *** ## Next Steps Configure providers, models, thinking levels, and fallbacks Complete config.json5 reference with all fields