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.

---

Defining an Agent

Agents are defined in config.json5 under agents:

{
  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 for details.

For the complete list of all config fields and their defaults, see the Config Reference.

---

Tool Permissions

Tools are provided by plugins and assigned to agents by name:

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

exec: git status        # calls the git plugin tool
exec: gh issue list     # calls the github plugin tool

See 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.

{
  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/<name>/ in the sandbox. The system prompt references them; the agent reads the docs when relevant:

exec: cat /skills/code-review/README.md

See Extensibility → Skills for details.

---

Sandbox Customization

Docker Image

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:

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

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:<agent>:default
Telegram (plugin)	telegram:<chatId> or telegram:<chatId>:<threadId>

Session Commands (TUI)

/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

{
  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

LLM Providers

Configure providers, models, thinking levels, and fallbacks

Full Config Reference

Complete config.json5 reference with all fields