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 - Continue, Cursor, custom scripts - can use whatever provider and model Bodega currently has configured, including local models.

Three 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 → Connections → 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 a pre-filled OPENAI_BASE_URL / OPENAI_API_KEY snippet for OpenAI-compatible clients. Bodega does not serve an Anthropic Messages (/v1/messages) route, so clients that only speak that API cannot use this server.

With the API Server on, Bodega also serves MCP at http://localhost:1337/mcp (Streamable HTTP, same port and API key as the API Server). Any MCP client can then use what Bodega keeps on your machine: query_memory and save_memory (your saved memories), query_knowledge (the knowledge base), query_docs (these docs), and query_map (ask the Bodega Map about a project; pass projectPath). Nothing else is exposed - no shell, no file access, no web tools - and nothing leaves the machine.

Claude Code:

claude mcp add --transport http bodega http://localhost:1337/mcp

Add --header "Authorization: Bearer <your key>" if you set an API key. Settings → Connections → API server shows the exact command for your port and key. The endpoint is stateless: every request is answered on its own, so there is no session to resume and GET /mcp answers 405.

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 INTERNAL names (mcp_<serverId>_<toolName>, where serverId is an opaque generated id like srv_m1a2b3c9) so they don't collide with Bodega's built-in tools or across servers with the same tool name.

The internal id is a routing detail, not something you'll normally see: the approval card and OS notification show the server's human-readable name (the one you typed when adding it), falling back to the internal id only for a server that has none.

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

Each connected server row shows the MCP version it negotiated, for example MCP 2026-07-28. Bodega speaks both the current protocol (2026-07-28, where the client asks the server to describe itself) and the older handshake, and tries the current one first. A server that only knows the older one is labelled legacy. If the current protocol could not be negotiated at all, Bodega retries once with the older handshake and labels it legacy (fallback). Either way it works the same. A per-server protocol setting (auto, legacy, or 2026-07-28 to require it) is available in the MCP server config.

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 → Connections → 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.

Some hosted MCP servers do not take a pasted token - they want you to sign in (OAuth 2.1). For those:

1. Add the server as a Streamable HTTP server with its URL.
2. On the server row, set Auth to Sign in with OAuth and click Sign in.
3. Your system browser opens the provider's consent page. Approve it; the page then says you can close the tab, and the row flips to Connected on its own.

Bodega registers itself with the provider (no client secret is ever typed), keeps the tokens encrypted on this machine, and refreshes them in the background. If the provider ever wants a fresh sign-in, the row shows Sign in required rather than retrying forever - click Sign in again. Sign out forgets the tokens. Sign-in is refused while air-gap mode is on, like every other network server.

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 Client Protocol) lets an external coding agent - Claude Code, Gemini CLI, Codex, Cursor, GitHub Copilot (preview) - run inside a Bodega chat or as a Fleet member, with Bodega wrapped around it: your memory and project rules go in, its edits go through Bodega's approvals, and every turn ends with a review of what changed. Each external agent runs in its own sandboxed git worktree, the same isolation used by Bodega's own 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.

Every harness turn ends with a harness review card: the files it changed and, when auto-verify is on, the result of your project's verify command. The harness stays attached to the session between turns, so it keeps its own working memory as well as Bodega's.

External agents are on by default; acp.client_mode_enabled: false turns them off.

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

In the Chat composer and in Code Mode's Agent panel, under ⋯ More options, the harness control lists Bodega plus every ACP agent installed on this machine. Bodega looks harnesses up on your login shell's PATH - the same one your terminal uses - so an adapter installed by npm under nvm, Volta or Homebrew is found even when Bodega was launched from the Dock or a launcher. If a harness still shows as not installed, run which <adapter> in a terminal: if that fails too, the install is not on your PATH. Pick one and the next turns run there; pick Bodega to switch back. The thread is one transcript either way - a Bodega turn can follow a Claude Code turn and see what it did.

What the harness receives on each turn: your project rules, what Bodega remembers, and the conversation so far (only what is new since its last turn, once it is attached). What Bodega keeps: approvals for its file and shell work, the review card at the end of the turn, and the reply in your transcript. The control is hidden when no harness is installed, when air-gap is on, or when ACP client mode is off.

CLI: bodega --harness claude-code starts a session on that harness; /harness <kind> switches mid-session; /harness bodega switches back.

Your agent, your login, your bill. A harness runs with its own sign-in, and its usage is billed to your own plan or subscription with that provider. Bodega never reads, stores or passes on that login: it strips every login-token variable from the harness's environment, never offers the provider's sign-in inside Bodega, and never installs anything. Sign in once in your own terminal (Settings → Connections → External coding agents shows each agent's own command).

No adapter installed? If the program itself is on your PATH but its ACP adapter is not (today: the claude program without claude-code-acp), the harness still runs, in the program's plain headless mode, and shows as (headless). In that mode it cannot ask you before each step: anything it would ask about is declined unless your coding agent's own settings already allow it (its own allow rules still apply). Ask runs its default mode, Plan runs its plan mode, and Act lets it edit files. Install the adapter for step-by-step approvals.

Share Bodega context (Settings → Connections → External coding agents, off by default) gives the harness Bodega's local MCP server: saved memories, the knowledge base, the docs and the project map, with no shell or file tools. It needs the API server on (Settings → Connections → API server), is never shared while air-gap or the project's vault is on, and is only offered to a harness that says it can connect to an HTTP MCP server. It needs the ACP adapter: a harness running in headless mode gets no Bodega tools. It takes effect when a harness session starts.

Sub-agents run on (same page) sends sub-agent work to an installed harness instead of a model. See Sub-agents.

CLI: these three are app-only for now; bodega --harness runs over the ACP adapter.

1. Open Settings → Connections → External coding agents.
2. Each agent (Claude Code, Gemini CLI, Codex, Cursor, GitHub Copilot) 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 auth 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. For GitHub Copilot (preview): npm install -g @github/copilot, then run copilot and /login once in a terminal (login does not work over ACP). GH_TOKEN / GITHUB_TOKEN in your environment are not passed through.
8. Paste the API key for Claude Code, Gemini, or Codex in the key field and click Save.
9. 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 → Agent → 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 → Agent → 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 → Connections → 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 → Models & Providers → Spending & limits.

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

1. Open Settings → Models & Providers → Cloud fallback.
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 → Models & Providers → Spending & limits.

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.

A plugin is a folder or .zip with a plugin.json manifest, optionally a skills/ folder (one or more skills, same format as a normal skill import), and optionally an mcp.json listing MCP servers to add. Installing a plugin is really three existing imports - manifest, skills, MCP - run together under one name.

Install goes through two steps: stage parses the plugin and reports what it contains (skills, MCP servers, any warnings) without changing anything, then commit writes it. Nothing is applied at stage time - you can stage a plugin and walk away without touching your setup.

A skill inside a plugin can carry grants - tools, policy, verification, completion frontmatter keys that expand what the skill can do beyond a plain workflow. Grants are stripped at stage time and only re-attached to a skill you explicitly approve, grant by grant. An unapproved grant is dropped, not silently kept.

An MCP server in the plugin that needs network access is blocked while air-gap mode is on - the plugin's skills still install, and you get a warning instead of a silent partial install.

Settings → Connections → Plugins has an Import Plugin button that walks the same stage/commit flow the CLI uses. Choose a folder or a .zip; the panel stages it and shows a preview - every skill and MCP server the plugin contains, any name collisions, and (for the skills) which grants it's asking for - before anything is written. Nothing is installed at this point; closing the preview writes nothing.

If a skill in the plugin requests grants, each one shows as its own unchecked checkbox. Nothing is approved by default - you tick exactly the grants you want re-attached, per skill, then click Install Plugin. An MCP server that needs network access while air-gap mode is on shows an inline warning ("Air-gap mode blocks servers with network access") right in the preview, before you commit - it still installs disabled rather than failing the whole plugin.

Installed plugins are listed below the Import button, each showing the skills and MCP servers it contributed and when it was installed. Remove deletes only that plugin's own contributions - a skill or MCP server you separately created under the same name is never touched. Re-importing a plugin under the same name is how you update it: anything the new version drops is cleaned up automatically, anything it still declares is kept (including whether you'd manually enabled its MCP server).

bodega plugin install <path-or-zip>

This stages the plugin, prints what it contains, then commits it. Add --dry-run to stage and preview only - nothing is written.

If any skill in the plugin has grants, you're asked to approve them per skill before commit. Interactively, that's a prompt per skill. In a script or CI, pass --approve-grants:

bodega plugin install ./my-plugin --approve-grants review:tools,policy;lint:verification

Outside a terminal (no TTY) with grants pending and no --approve-grants flag, the install fails rather than guessing. This is deliberate - a plugin with grants can expand what a skill is allowed to do, and a non-interactive run has no way to ask you. Pass --approve-grants explicitly (even an empty value for "approve nothing") or run it interactively.

The CLI and the app's Settings panel drive the same backend routes, so a plugin installed from one shows up when the other lists installed plugins.

Import a plugin whose name is already installed and the preview gains a Changes panel: each skill and MCP server is marked new, changed, removed or unchanged (by content, not by name), with the old and new version. Tick keep current on a changed item to leave your copy alone, or keep it on a removed item to keep it installed; everything else is written. Unchanged files are not touched. If the folder changes between the preview and Update Plugin, Bodega refuses and asks you to choose the folder again, so you never install something you did not see.

CLI: bodega plugin install <path> prints the same table when the name is already installed; --dry-run previews only.

Settings → Connections → Plugins → Export… turns your own skills and MCP server declarations into an Agent Plugins v1.0.0 folder: plugin.json, one skills/<name>/SKILL.md per skill (copied exactly), and mcp.json. Give it a name (lowercase, digits, - or _), a version, pick the members, choose a folder, done - zip it and share it, or hand it to Cursor, Copilot or another Bodega.

What never leaves: API keys, OAuth tokens, any Authorization header, and whether this machine allowed a server network access. A stdio server's credential is exported as the variable name only. Built-in skills are not yours to publish and are not listed. Bodega also refuses to export into its own data folders.

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 & Providers → Models and install it there first if you haven't.
2. Download an embedding model via Settings → Models & Providers → Models → Discover tab (nomic-embed-text and bge-small are good starting points).
3. Open Settings → Prompts & Memory → Knowledge base → Advanced → Embeddings (Codebase index for code search, Knowledge and memory for knowledge search).
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.