Documentation
Welcome to our documentation. Choose a topic below to get started.
Index
Concepts
Overview
The mental model behind Bodhi App: one server, many compatibility layers, local + remote inference, MCP tools, role-based auth
Deployment Modes
Tauri desktop vs Docker single-tenant — the two ways to run Bodhi App, and how to pick
Models, Aliases, and Files
The three things "model" can mean in Bodhi — file vs alias vs API model — and how they relate
API Compatibility
Why Bodhi exposes OpenAI, Anthropic, Gemini, and Ollama wire formats simultaneously — and what that means for your client
Auth and Roles
OAuth2 PKCE, four roles (User / PowerUser / Manager / Admin), session cookies vs API tokens, and how scopes work
MCP Overview
Model Context Protocol in Bodhi: per-user instances, three auth methods, the playground, and the MCP proxy for external apps
Features
Chat UI
Walkthrough of Bodhi App's built-in chat interface — layout, streaming, model picker, conversation history
MCPs Overview
How MCP servers, instances, and tool execution fit together in Bodhi App
Overview
Tour of the Models section: what each sub-page is for, and where the model file vs alias vs API model distinction lives in the UI
Tool Calling
How MCP tools surface in chat, per-conversation tool selection, and the agentic loop that executes tool calls inline
MCP Setup
Connect to an MCP server and create a user MCP instance with whitelisted tools
Parameters and System Prompt
Tune sampling — temperature, top-p, max tokens, stop words — and override the system prompt per conversation
MCP Auth Methods
Pick between Header, OAuth2 preregistered, and OAuth2 Dynamic Client Registration for connecting to an MCP server
MCP Playground
Interactive tool runner for testing MCP servers and individual tools at /ui/mcps/playground
Pre-registered Servers (Admin)
Publish MCP servers to the workspace catalog so users can instantiate them without copying URLs or auth credentials
MCP Usage
Enable MCP tools in chat conversations, control whitelists per chat, and read tool execution feedback
Model Aliases
Create, edit, and manage model aliases — the named recipes Bodhi uses to launch llama.cpp with the right file and parameters
Model Files
List, inspect, and remove the GGUF files Bodhi has cached locally for inference
Model Downloads
Pull GGUF model files from HuggingFace into Bodhi’s local cache, with background progress and idempotent retries
API Models
Connect Bodhi to a remote provider — OpenAI, OpenAI Responses, Anthropic, Anthropic OAuth, or Gemini — and proxy requests through your local server
Anthropic OAuth
Use a Claude.ai / Anthropic Console subscription with Bodhi via an OAuth Bearer token instead of an API key
App Settings
View runtime configuration, see where each value is sourced from, and edit the small subset that the UI allows
Auth Overview
Roles vs token scopes, session cookies vs API tokens, and the four feature pages that follow
User Access Requests
Request a role to access Bodhi App after your first OAuth login
User Management
Approve access requests, change user roles, and remove users from the Users page
API Tokens
Mint, scope, and rotate database-backed API tokens for programmatic access
App Access Management
Review and grant scoped access to third-party apps that want to use your MCPs and APIs
Deployment
Deployment Overview
Pick the right way to run Bodhi App — Tauri desktop or Docker single-tenant
Desktop (Tauri)
Tauri desktop deep dive — architecture, file layout, system tray, per-platform secret storage, logs, updates
Docker
Deploy Bodhi App with Docker — CPU, CUDA, ROCm, Vulkan, MUSA, Intel, and CANN variants
Reverse Proxy
TLS termination and rate limiting in front of Docker — Nginx and Caddy examples
Developer
Getting Started
SDK reference for integrating React applications with Bodhi using @bodhiapp/bodhi-js-react — provider setup, hooks, models, chat, embeddings, and MCP tools
Advanced Patterns
Advanced SDK usage — login with MCP access requests, agentic tool calling, extension SDK, custom client configuration, error handling
Getting Started
End-to-end tutorial for building apps that connect to Bodhi — from OAuth registration through API calls and MCP tool execution
Building Third-Party Apps
End-to-end lifecycle for apps built on BodhiApp — OAuth client registration, user consent flow, scoped token usage, and the security model
Browser Extension
How the Bodhi App browser extension exposes authenticated endpoints to web pages, and how SDK clients auto-detect it
App Access Requests
Resource consent model for third-party apps — access request API flow, user review, role privileges, and MCP instance approval
OpenAPI Reference
Interactive Swagger UI, the per-format compat guides, endpoint prefixes, and CORS policy
Api Compatibility
Overview
Functional entry point for the API Compatibility section — endpoint map, unified auth, and how each compat layer is laid out
OpenAI Chat Completions
Use /v1/chat/completions with any OpenAI SDK — streaming, tool calling, and the Bodhi-specific model resolution rules
OpenAI Responses
/v1/responses async polling for reasoning and long-running tasks — pure pass-through to upstream providers, with strict ApiFormat rules
OpenAI Embeddings
Use /v1/embeddings against local or remote embedding models with the standard OpenAI SDK
Anthropic Messages
Use the Anthropic Messages API against Bodhi — header rewriting, model resolution, streaming, and the API-key vs Anthropic-OAuth split
Gemini
Use the Google Gemini /v1beta/* surface against Bodhi — header rewriting, action dispatch, streaming, and embeddings
Ollama (deprecated)
/api/* compatibility for legacy Ollama clients — limited surface, kept for migration only
MCP Proxy
Use Bodhi as an authenticated MCP front door — the per-instance proxy at /bodhi/v1/apps/mcps/{id}/mcp, JSON-RPC over HTTP, and how upstream auth is hidden from your callers
Error Format
The error envelopes you can see — Bodhi-native, OpenAI-style, and the provider-shaped wrappers the Anthropic and Gemini compat layers return
Advanced
Architecture
How a request travels through Bodhi App: from the wire to the inference engine and back
Security Model
What Bodhi App protects, what it relies on the deployment to provide, and how to harden a self-hosted installation
Inference Stack
How Bodhi App invokes llama.cpp: variants, GGUF resolution, runtime arguments, and the keep-alive timer
Performance Tuning
Choosing variants, quantization, context window, and concurrency to match Bodhi App to your hardware
Observability
Logs, settings introspection, the background queue, and what is honest about today’s observability gaps in Bodhi App
Reference
Environment Variables
Alphabetical reference for every BODHI_* / HF_* environment variable Bodhi App reads at startup or runtime
Settings Precedence
How Bodhi merges settings from CLI flags, environment, database, settings.yaml, and built-in defaults — and which two settings the UI can edit
Roles and Scopes
Capability matrix — what User, PowerUser, Manager, and Admin can do, and how API token scopes interact with the issuing user role
Error Codes
Lookup index for the most common error codes returned across Bodhi-native, OpenAI, Anthropic, and Gemini envelopes
Glossary
Alphabetical glossary of terms used across the Bodhi App docs