Project status — v0.1.0 (early preview). Busibox is suitable for evaluation, lab use, and design-partner pilots. It has not yet had an independent security audit, and APIs/schemas may change before 1.0. See CHANGELOG.md for known limitations.

A self-hosted AI platform that keeps your data on your infrastructure.

Busibox integrates document processing, semantic search, AI agents, and custom applications into a single platform — running on Docker or Proxmox LXC containers with enterprise-grade security baked in.

Think of it as a Linux distribution for AI: install it on your hardware, and you get a complete stack for building AI-powered workflows without sending a single byte to the cloud (unless you choose to).

You shouldn't have to choose between powerful AI and data sovereignty.

Most AI platforms require uploading your documents to third-party servers. Busibox runs entirely on infrastructure you control — a local server, a Proxmox cluster, or Docker on your laptop. Your documents, embeddings, conversations, and search indexes never leave your network.

Upload PDFs, Word, Excel, PowerPoint, images (with OCR), or Markdown. Busibox automatically extracts text, chunks it, generates embeddings, and indexes everything for search. Schema-driven extraction pulls structured fields (dates, names, amounts) from unstructured documents.

Natural language queries against your document library. Combines vector search (semantic), BM25 (keyword), graph-based retrieval, and LLM reranking — all filtered by the user's permissions. Ask "What are the budget assumptions for Q3?" instead of guessing keywords.

Conversational agents that search your documents (RAG), browse the web, accept file attachments, remember context, and stream responses with source citations. Configure agents with custom instructions, tools, and model routing per task. Built-in guardrails enforce request limits, token budgets, cost ceilings, and timeouts — so autonomous agents can't consume unbounded resources.

LiteLLM gateway routes requests to local models (vLLM on NVIDIA GPUs, MLX on Apple Silicon) or cloud providers (OpenAI, Anthropic, AWS Bedrock) — per agent, per task. Use a fast local model for extraction and a frontier model for complex reasoning, all through one API.

Build and deploy Next.js apps that inherit Busibox auth, data access, and AI capabilities. A shared library (@jazzmind/busibox-app) provides SSO, data API clients, chat components, and search — so you write domain logic, not plumbing.

Connect agents to Telegram, Signal, Discord, WhatsApp, and email. Users interact with AI in the tools they already use.

Manage multiple Busibox installations from a single workstation. The CLI supports deployment profiles for Docker, Proxmox LXC, and Kubernetes backends — self-hosted or cloud. Deploy to staging, test, then promote to production with separate vault keys, SSH configs, and environment settings per profile.

┌─────────────────────────────────────────────────────────┐
│                       Browser                           │
└────────────────────────┬────────────────────────────────┘
                         │
                    ┌────▼────┐
                    │  nginx  │  reverse proxy + SSL
                    └────┬────┘
            ┌────────────┼────────────────┐
            ▼            ▼                ▼
      ┌──────────┐ ┌──────────┐    ┌───────────┐
      │  Portal  │ │  Agents  │    │ User Apps │
      └────┬─────┘ └────┬─────┘    └─────┬─────┘
           └─────────────┼────────────────┘
                         ▼
        ┌────────────────────────────────┐
        │         API Layer              │
        │  AuthZ · Data · Agent · Search │
        │  Docs · Deploy · Embedding     │
        └───────────────┬────────────────┘
                        ▼
        ┌────────────────────────────────┐
        │       Infrastructure           │
        │  PostgreSQL · Milvus · MinIO   │
        │  Redis · LiteLLM · vLLM       │
        └────────────────────────────────┘

Each service runs in its own isolated container. Compromise in one container does not grant access to another. All inter-service communication uses audience-scoped RS256 JWTs verified via JWKS — no shared secrets, no static tokens.

Busibox is single-tenant and multi-user — each installation serves one organization with strong isolation between users. Security is architecture, not a feature bolted on later.

• Zero Trust Authentication — OAuth2-based AuthZ service is the sole token authority. RS256-signed JWTs verified via JWKS; subject token exchange scopes tokens per service. No shared secrets, no static API keys.
• Passwordless Auth — Passkeys (biometrics/security keys), TOTP, or magic links. No passwords by design. SSO via EntraID, SAML, and other identity providers.
• Row-Level Security — PostgreSQL RLS enforces access at the database level. Even with an application bug, the database won't return unauthorized rows.
• RBAC Everywhere — Documents, agents, and apps are assigned to roles. Users see only what their roles permit. Agents inherit the calling user's permissions.
• Envelope Encryption — Files encrypted at rest with Master Key → Key Encryption Keys → Data Encryption Keys, per file. TLS for all inter-service communication.
• Audit Trail — Auth events, token exchanges, and admin actions logged with timestamps, user IDs, and IP addresses.
• Built-in Security Testing — OWASP API Security Top 10 test suite covering auth bypass, injection, fuzzing, and endpoint coverage. Run with the CLI or make test-security.

• Enterprise teams that need AI but can't send sensitive data to third parties
• Consultancies building AI solutions for clients on shared infrastructure
• Regulated industries (legal, finance, healthcare, government) with data residency and audit requirements
• AI-native organizations that want control without stitching together a dozen tools

The fastest way to evaluate Busibox is to run the whole stack locally on Docker and bring your own LLM API key. No GPU and no local model downloads are required for a first run. Local inference (vLLM / Ollama / MLX) is an optional add-on — see "Optional: local inference" below.

Prerequisites: Docker + Docker Compose, ~16 GB free disk for images, and one of: an OpenAI key, an Anthropic key, or AWS Bedrock credentials.

git clone https://github.com/jazzmind/busibox.git
cd busibox

# Start from the example env file and add a cloud LLM key
cp env.local.example .env.local
# Edit .env.local and set ONE of:
#   OPENAI_API_KEY=sk-...
#   ANTHROPIC_API_KEY=sk-ant-...
#   AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_REGION_NAME (for Bedrock)

make docker-up

The Portal is then available at http://localhost:3000. The first user to sign up becomes the admin (configurable via ADMIN_EMAIL). See QUICKSTART.md for details, and docs/administrators/ for the full operator guide.

Why cloud-key by default? A first-run evaluation should focus on the platform — auth, RAG, agents, search — not on model downloads, GPU drivers, or quantisation tradeoffs. Once you've verified Busibox does what you need, swap in local models with the add-on pack. See docs/administrators/local-models-addon.md for the design.

For air-gapped or fully on-prem deployments, Busibox routes through LiteLLM to local backends:

The local-model add-on pack is documented at docs/administrators/local-models-addon.md. For multi-host or Proxmox deployments, the Busibox CLI handles GPU detection and model selection automatically.

The Busibox CLI is an interactive terminal UI that walks you through profile setup, hardware profiling, model selection, and deployment across Docker, Proxmox LXC, and Kubernetes targets. It handles SSH connectivity, encrypted vault passwords, and service health from one interface.

cd cli/busibox
cargo build --release
./target/release/busibox

See docs/administrators/01-quickstart.md for the full CLI flow.

The app template and @jazzmind/busibox-app library give you:

• SSO out of the box — SessionProvider handles auth, token refresh, and 401 retry
• Data API client — structured CRUD with automatic RLS enforcement
• Chat components — SimpleChatInterface for agent-powered UIs
• Search client — hybrid search with permission filtering
• Deploy in one command — deploy from the CLI or via MCP

# Start from the template
git clone <template-repo> my-app
cd my-app && npm install && npm run dev

Apps are cloned and built at runtime — code changes deploy without rebuilding containers.

Three MCP servers provide structured access for AI coding agents (Cursor, Claude Code):

AI agents should use MCP tools rather than make targets directly. The make interface is an internal implementation detail used by the CLI and MCP servers — it requires vault password setup that the CLI handles automatically.

make mcp   # Build all servers and write Cursor config

busibox/                        # This repo — infrastructure, APIs, provisioning
├── docs/                       #   Documentation (by audience)
├── srv/                        #   Service source code
│   ├── agent/                  #     Agent API (FastAPI)
│   ├── data/                   #     Data API + Ingest Worker
│   ├── docs/                   #     Docs API
│   └── deploy/                 #     Deploy API
├── provision/
│   ├── ansible/                #     Ansible roles and inventory
│   └── pct/                    #     Proxmox container scripts
├── scripts/                    #   Admin workstation scripts
├── tools/                      #   MCP servers and utilities
└── specs/                      #   Project specifications

Related repositories:

See CONTRIBUTING.md for the full contributor guide. The short version:

1. Read the architecture docs in docs/developers/architecture/
2. Set up a local development environment with Docker: make install SERVICE=all
3. Run tests: make test-docker SERVICE=<service>
4. Follow the organization rules in .cursor/rules/ for file placement and naming

Participation is governed by our Code of Conduct. Security issues should be reported privately — see SECURITY.md.

See CLAUDE.md for detailed development workflow and conventions.

Busibox is released under the MIT License. The project source code is MIT-licensed; some optional and bundled third-party components carry their own licenses. See NOTICE for the per-component breakdown — most relevant for operators who plan to redistribute a Docker image of the platform.