vibe-kanban/docs/configuration-customisation/agent-configurations.mdx

---
title: "Agent Profiles & Configuration"
description: "Configure and customise coding agent variants with different settings for planning, models, and sandbox permissions"
---

Agent profiles let you define multiple named variants for each supported coding agent. Variants capture configuration differences like planning mode, model choice, and sandbox permissions that you can quickly select when creating attempts.

<Info>
Agent profiles are used throughout Vibe Kanban wherever agents run: onboarding, default settings, attempt creation, and follow-ups.
</Info>

## Configuration Access

You can configure agent profiles in two ways through Settings → Agents:

<Tabs>
<Tab title="Form Editor">
  Use the guided interface with form fields for each agent setting.

  <Frame>
  <img src="/images/coding-agent-configurations.png" alt="Agent configuration form editor interface" />
  </Frame>
</Tab>

<Tab title="JSON Editor">
  Edit the underlying `profiles.json` file directly for advanced configurations.

  <Frame>
  <img src="/images/coding-agent-configurations-json.png" alt="JSON editor for agent configurations" />
  </Frame>
</Tab>
</Tabs>

<Note>
The configuration page displays the exact file path where your settings are stored. Vibe Kanban saves only your overrides whilst preserving built-in defaults.
</Note>

## Configuration Structure

The profiles configuration uses a JSON structure with an `executors` object containing agent variants:

```json profiles.json
{
  "executors": {
    "CLAUDE_CODE": {
      "DEFAULT": { "CLAUDE_CODE": { "dangerously_skip_permissions": true } },
      "PLAN":    { "CLAUDE_CODE": { "plan": true } },
      "ROUTER":  { "CLAUDE_CODE": { "claude_code_router": true, "dangerously_skip_permissions": true } }
    },
    "GEMINI": {
      "DEFAULT": { "GEMINI": { "model": "default", "yolo": true } },
      "FLASH":   { "GEMINI": { "model": "flash",   "yolo": true } }
    },
    "CODEX": {
      "DEFAULT": { "CODEX": { "sandbox": "danger-full-access" } },
      "HIGH":    { "CODEX": { "sandbox": "danger-full-access", "model_reasoning_effort": "high" } }
    }
  }
}
```

<AccordionGroup>
<Accordion title="Structure Rules">
  - **Variant names**: Case-insensitive and normalised to SCREAMING_SNAKE_CASE
  - **DEFAULT variant**: Reserved and always present for each agent
  - **Custom variants**: Add new variants like `PLAN`, `FLASH`, `HIGH` as needed
  - **Built-in protection**: Cannot remove built-in executors, but can override values
</Accordion>

<Accordion title="Configuration Inheritance">
  - Your custom settings override built-in defaults
  - Built-in configurations remain available as fallbacks
  - Each variant contains a complete configuration object for its agent
</Accordion>
</AccordionGroup>

## Agent Configuration Options

<Tabs>
<Tab title="CLAUDE_CODE">
  <ParamField path="plan" type="boolean">
  Enable planning mode for complex tasks
  </ParamField>

  <ParamField path="claude_code_router" type="boolean">
  Route requests across multiple Claude Code instances
  </ParamField>

  <ParamField path="dangerously_skip_permissions" type="boolean">
  Skip permission prompts (use with caution)
  </ParamField>

  [View full CLI reference →](https://docs.anthropic.com/en/docs/claude-code/cli-reference#cli-flags)
</Tab>

<Tab title="GEMINI">
  <ParamField path="model" type="string">
  Choose model variant: `"default"` or `"flash"`
  </ParamField>

  <ParamField path="yolo" type="boolean">
  Run without confirmations
  </ParamField>

  [View full CLI reference →](https://google-gemini.github.io/gemini-cli/)
</Tab>

<Tab title="AMP">
  <ParamField path="dangerously_allow_all" type="boolean">
  Allow all actions without restrictions (unsafe)
  </ParamField>

  [View full documentation →](https://ampcode.com/manual#cli)
</Tab>

<Tab title="CODEX">
  <ParamField path="sandbox" type="string">
  Execution environment: `"read-only"`, `"workspace-write"`, or `"danger-full-access"`
  </ParamField>

  <ParamField path="approval" type="string">
  Approval level: `"untrusted"`, `"on-failure"`, `"on-request"`, or `"never"`
  </ParamField>

  <ParamField path="model_reasoning_effort" type="string">
  Reasoning depth: `"low"`, `"medium"`, or `"high"`
  </ParamField>

  <ParamField path="model_reasoning_summary" type="string">
  Summary style: `"auto"`, `"concise"`, `"detailed"`, or `"none"`
  </ParamField>

  [View full documentation →](https://github.com/openai/codex)
</Tab>

<Tab title="CURSOR">
  <ParamField path="force" type="boolean">
  Force execution without confirmation
  </ParamField>

  <ParamField path="model" type="string">
  Specify model to use
  </ParamField>

  [View full CLI reference →](https://docs.cursor.com/en/cli/reference/parameters)
</Tab>

<Tab title="OPENCODE">
  <ParamField path="model" type="string">
  Specify model to use
  </ParamField>

  <ParamField path="agent" type="string">
  Choose agent type
  </ParamField>

  [View full documentation →](https://opencode.ai/docs/cli/#flags-1)
</Tab>

<Tab title="QWEN_CODE">
  <ParamField path="yolo" type="boolean">
  Run without confirmations
  </ParamField>

  [View full documentation →](https://qwenlm.github.io/qwen-code-docs/en/cli/index)
</Tab>
</Tabs>

### Universal Options

These options work across multiple agent types:

<ParamField path="append_prompt" type="string | null">
Text appended to the system prompt
</ParamField>

<ParamField path="base_command_override" type="string | null">
Override the underlying CLI command
</ParamField>

<ParamField path="additional_params" type="string[] | null">
Additional CLI arguments to pass
</ParamField>

<Warning>
Options prefixed with "dangerously_" bypass safety confirmations and can perform destructive actions. Use with extreme caution.
</Warning>

## Using Agent Configurations

<CardGroup cols={2}>
<Card title="Default Configuration" icon="gear">
  Set your default agent and variant in **Settings → General → Default Agent Configuration** for consistent behaviour across all attempts.
</Card>

<Card title="Per-Attempt Selection" icon="rocket">
  Override defaults when creating attempts by selecting different agent/variant combinations in the attempt dialogue.
</Card>
</CardGroup>

## Related Configuration

<Note>
MCP (Model Context Protocol) servers are configured separately under **Settings → MCP Servers** but work alongside agent profiles to extend functionality.
</Note>

<CardGroup cols={2}>
<Card title="MCP Server Configuration" icon="server" href="/integrations/mcp-server-configuration">
  Configure MCP servers within Vibe Kanban for your coding agents
</Card>

<Card title="Vibe Kanban MCP Server" icon="plug" href="/integrations/vibe-kanban-mcp-server">
  Connect external MCP clients to Vibe Kanban's MCP server
</Card>
</CardGroup>