Integrations

The API Server runs a local HTTP server on port 1337 (configurable) that speaks the OpenAI API. Any tool that supports an OpenAI-compatible endpoint - Claude Code, Continue, Cursor, custom scripts - can use whatever provider and model Bodega currently has configured, including local models.

Two endpoints:

The server binds to 127.0.0.1 only - it is not reachable from other machines. Rate limit: 60 requests per 60-second window per IP.

1. Open Settings → API Server.
2. Toggle Enable API Server on.
3. Change the port if 1337 conflicts with anything (default is fine for most setups).
4. Optionally set an API Key. If set, every request must include Authorization: Bearer <key>. Leave blank to allow all local connections without auth.
5. Restart the app - the toggle takes effect after restart.

Once running, the Settings panel shows the base URL (http://localhost:1337/v1) with a copy button and pre-filled setup snippets for Claude Code and other OpenAI-compatible clients.

Set ANTHROPIC_BASE_URL (or the equivalent env var for your client) to http://localhost:1337/v1 and point the client at Bodega instead of the real endpoint:

export ANTHROPIC_BASE_URL=http://localhost:1337/v1
export ANTHROPIC_API_KEY=<your-bodega-api-key-or-any-string-if-no-key-set>

The Settings panel generates this snippet for you when the server is enabled - use the copy button rather than typing it.

MCP (Model Context Protocol) connects Bodega to external stdio servers that expose additional tools - file access on remote paths, GitHub operations, web search via Brave, SQLite queries, and more. Each server's tools are injected into the agentic loop under namespaced names (mcp_<serverName>_<toolName>) so they don't collide with Bodega's built-in tools.

Built-in presets: Filesystem, GitHub, Brave Search, SQLite, Memory, Fetch, Sequential Thinking.

Servers auto-reconnect if they crash. When air-gap mode is on, any server marked Requires Network is blocked - it cannot be added or connected.

1. Open Settings → MCP Servers.
2. Click a preset card to pre-fill the form, or enter Name, Command, Args, and the Requires Network toggle manually.
3. Click Add Server. It connects immediately and its tools appear in the agentic loop.
4. Use the Connect / Disconnect toggle per server to enable or disable individual servers without removing them.
5. Click Delete to remove a server - its tools are unregistered instantly.
6. To store a per-server API credential: expand the server row and fill in the credential field. Credentials are stored under mcp.<serverId>_api_key.

The server list refreshes every 5 seconds and shows live connection status and tool count.

Expand a server row to narrow which of its raw MCP tools Bodega exposes, and to control how a connection failure is handled:

• Tool allowlist (enabledTools) - list only the tool names you want; everything else from that server is hidden. An empty allowlist means "all tools".
• Tool denylist (disabledTools) - list tool names to drop. The denylist subtracts from whatever the allowlist let through.
• Precedence: the allowlist is applied first, then the denylist subtracts from it. The filter can only narrow what security already permits - it never grants a tool that air-gap or another guard would block.
• Required (required) - when on, a server that fails to connect at boot fails fast (error log + status broadcast) instead of being silently retried in the background. Use it for a server your workflow depends on so a missing dependency is obvious. The default (off) keeps retrying quietly.

These are per-server config fields on MCPServerConfig - set them in the expanded server card.

ACP (Agent Coding Protocol) lets you add external coding agents - Claude Code, Gemini CLI, Codex, Cursor - as participants in a Fleet run. Each external agent runs in its own sandboxed git worktree, the same isolation used by Bodega's own Fleet sessions.

Bodega acts as the ACP client here: it spawns the external agent process, handles the RPC handshake, and routes the agent's file system and shell requests through Bodega's own FileSystemTool and ShellTool. The sandbox, credential scan, and SSRF block all apply to external agents - they cannot reach outside the worktree or exfiltrate keys.

ACP sessions appear in the Fleet panel with an external - not QEL-verified badge. They are not run through QEL.

Air-gap blocks all ACP agents - the panel shows an amber notice when air-gap is active.

1. Open Settings → ACP Agents.
2. Each agent (Claude Code, Gemini CLI, Codex, Cursor) shows Installed or Not installed based on whether the binary is on PATH. An install command is shown for agents that are missing.
3. For Claude Code: run claude /login once in a terminal. The binary used is claude-code-acp (package @zed-industries/claude-code-acp), not the claude CLI.
4. For Gemini CLI: install with npm install -g @google/gemini-cli. Bodega invokes it with gemini --experimental-acp - not --acp.
5. For Codex: the binary is codex-acp (package @zed-industries/codex-acp).
6. For Cursor: no API key - Cursor uses your subscription. Run cursor-agent login once in a terminal first.
7. Paste the API key for Claude Code, Gemini, or Codex in the key field and click Save.
8. Once configured, these agents appear as options when you start a new Fleet run.

The ACP direction flips: instead of Bodega driving external agents, Bodega becomes an ACP agent that an external editor drives. Launch Bodega with --acp and it boots headless - no Electron window, no HTTP server on :3000 - and wires an NDJSON-RPC 2.0 transport over stdin/stdout.

Zed (or any ACP client) can then open sessions, send prompts, and receive streaming token and tool-call updates. All of Bodega's security still applies: FileSystemTool sandbox, ShellTool credential scan, WebFetchTool SSRF block. Sessions run in code mode with Ask permission mode - every tool call routes through the client's session/request_permission gate.

The cwd the client requests is realpath-resolved and must sit inside the allowed base directory (default: your home directory). Filesystem roots are rejected.

Add Bodega to Zed's agent_servers in your Zed settings.json:

{
  "agent_servers": {
    "Bodega One": {
      "command": "/path/to/bodega",
      "args": ["--acp"]
    }
  }
}

For development (no packaged binary):

{
  "agent_servers": {
    "Bodega One": {
      "command": "npx",
      "args": ["tsx", "/path/to/BodegaOne-dev/apps/desktop/backend/src/acp-server-boot.ts", "--acp"]
    }
  }
}

To restrict which directories Bodega will accept as project roots, set acp.allowed_projects_dir via the settings API (PUT /api/settings). There is no Settings panel UI for this in beta.26.

Any ACP client that can spawn a command works the same way: point it at the Bodega binary with the --acp argument and it gets the full agent over stdio. JetBrains AI Assistant and the Neovim ACP plugins both accept a command-plus-args agent definition - check their docs for where that configuration lives in your version. The agent side is identical regardless of the client: same sessions, same streaming updates, same permission gate per tool call.

Custom Agents let you save a named configuration - a system prompt, an optional pinned model, a tool allowlist, a read-only filesystem flag, and an iteration cap - and apply it in any Agent panel session.

A custom agent's tool allowlist is an intersection with the panel's tools. It can only narrow what the panel already has access to - it cannot escalate permissions. Safety guardrails always apply regardless of the system prompt.

Agents are stored per-user in the agent_definitions table.

Limits: name ≤ 100 chars, description ≤ 500 chars, system prompt ≤ 6,000 chars, iterations 1–50.

Create:

1. Open Settings → Custom Agents.
2. Click + New Agent.
3. Fill in: Name (required), Description (optional), System prompt (required - replaces the default agent identity), Model (optional - leave blank to inherit the panel's current model), Tool allowlist (checkboxes; leave all unchecked to allow all panel tools), Read-only filesystem toggle, Max iterations (optional, 1–50).
4. Click Save.

Use:

1. In Code mode, open the Agent panel (Ctrl+L).
2. Click the robot-icon dropdown in the panel header to open the Agent Profile Picker.
3. Select your custom agent. It stays active until you switch back to Default.

Edit or delete: go back to Settings → Custom Agents and modify or remove from the list.

Point Bodega at a plain task or a GitHub issue and it implements the change in an isolated git worktree on your machine, runs full QEL verification, and opens a pull request with the verification trace in the description. Nothing is sent to a cloud build.

This is not the Source Control panel. Source Control is for changes you make by hand: stage, commit, push, and review your own diff on the real working tree. GitHub Automation is autonomous: the agent writes the code in a throwaway worktree, verifies it, and the only thing that leaves your machine is a branch and a PR. Your working tree is never touched.

The apply policy decides what happens when a run finishes. Open a PR when verified gives a ready PR on a passing QEL score and a draft when it fails. Always open a draft parks every run as a draft for review. Dry run verifies but opens nothing. A failed verification never opens a green-looking PR.

They sit next to each other in the activity bar and both touch git, but they do opposite things. The git-branch icon is Source Control; the fork icon next to it is GitHub Automation.

The one overlap is push: Source Control pushes your current branch when you click it; GitHub Automation pushes a new bodega/ branch after a verified agent run, then opens the PR. Use Source Control for your own work; use GitHub Automation to hand a task off and get a verified PR back without touching your working tree.

1. Open Settings → Integrations → GitHub and paste a personal access token (classic with the repo scope, or fine-grained with Contents and Pull requests read/write). Click Save, then Test token to confirm the login and scopes. The token is stored as a local secret and is only ever sent to GitHub, never to Bodega.
2. In Code mode, open a project folder whose origin remote is a github.com repository.
3. Click the GitHub icon at the bottom of the activity bar to open the Automate dialog.
4. Choose Plain task and describe the change, or GitHub issue and enter owner/repo#123.
5. Optionally pick a custom agent under Run with so the run uses that agent's prompt, model, and tool allowlist.
6. Pick the apply policy and click Run. The run can take a few minutes; the dialog then shows the QEL score, files changed, and a link to the opened PR.

Cloud Boost adds a secondary cloud LLM that Bodega can switch to automatically or on demand. Use cases:

• Tasks too large for your local model's context window
• QEL verification failures - Boost activates automatically after two consecutive QEL fails
• Manual override - toggle Boost in the chat input toolbar for a single message

14 supported providers: Anthropic, OpenAI, Groq, Together AI, OpenRouter, Azure OpenAI, Google Gemini, Mistral AI, Cohere, DeepSeek, Fireworks AI, Qwen/DashScope, Kimi/Moonshot AI, Featherless AI.

Budget caps block new Boost requests at 100% of the daily or monthly limit and warn at 80%. Cost tracking appears in Settings → Spending.

Cloud Boost is blocked entirely when air-gap mode is on.

1. Open Settings → Cloud Boost.
2. Toggle Enable Cloud Boost.
3. Pick a cloud provider from the dropdown.
4. Paste your API key.
5. Optionally specify a model (leave blank for the provider's default).
6. Set a daily and monthly budget in USD.
7. Click Test Connection to confirm the key works.

Cost data is logged locally in SQLite - it never leaves your machine. View spend in Settings → Spending.

The Review button in the Git panel sends your current local diff to the active LLM for an AI-written code review - no data leaves the machine if you're running a local model.

What it reviews, in order:

1. Staged + working-tree changes - the "before I commit" diff. If there are any uncommitted changes, this is what you get.
2. Branch vs merge base - if the working tree is clean, Bodega falls back to the diff between your branch and main or master. This is the PR-scope review.

The diff is capped at 14,000 chars before sending. If truncation happens, the response says so.

The review output uses GitHub-flavored markdown with Critical, High, and Suggestions sections. It appears inline in the Git panel and can be dismissed with the X button - it is not saved.

1. Open Code mode and make sure a project folder is open.
2. Open the Git panel (Source Control tab in the activity bar, or Ctrl+Shift+G).
3. Make or stage some changes.
4. Click Review in the commit toolbar (next to the Generate commit message button).
5. A Reviewing… spinner shows on the button while the LLM works.
6. The review appears as a markdown block below the commit input.
7. Click X to dismiss it when you're done.

No separate model configuration is needed - it uses the same model as other code-mode operations.

When using llama.cpp as the embedding provider, Bodega can spawn and manage a separate llama-server process for embeddings. This is distinct from the chat llama-server (port 8080) - the embedding server runs on port 8081 and starts with the --embedding flag.

It starts lazily - not at app launch, but on the first embedding request. This powers Ask the Map and Knowledge Base semantic search without requiring you to manually run a second server.

The GGUF picker shows models already installed in your llama.cpp library, so you can select one without typing a path.

1. Make sure the llama.cpp binary is installed - go to Settings → Models and install it there first if you haven't.
2. Download an embedding model via Settings → Models → llama.cpp → Discover (nomic-embed-text and bge-small are good starting points).
3. Open Settings → Models (scroll to the Knowledge & Embeddings section) or Settings → Knowledge → Search & Embeddings.
4. Set Provider to llama.cpp.
5. Check Let Bodega manage the embedding server.
6. A dropdown appears showing installed GGUFs - select your embedding model. You can also type a full absolute path manually.
7. Optionally change the port (default 8081).

The server starts automatically on the first embedding operation.