Free AI events and workshopsChat with your CRM using AI: a practical AI agent workshop for CRM, business data, SMEs, and transformation teams.Sep 12, 2026, 1:00 PM Pacific Time

Batuk Documentation

Batuk docs for open-source enterprise AI chat.

Run Batuk with model providers, user-scoped RAG, shared workspaces, personal API keys, OpenAI-compatible model routes, token usage analytics, Better Auth, teams, audit, whitelabeling, storage, and Docker.

Start quick setup View comparisons Back to Batuk GitHub

Overview

What Batuk is for

Chat With Any Approved Model

Use Ollama, OpenAI, OpenRouter, Claude, Grok, Sarvam AI, or private OpenAI-compatible gateways from one chat workspace.

Document Chat and RAG

Upload, index, search, reindex, download, and delete documents with local or OpenAI embeddings.

Vector Store Choice

Run local JSON vectors by default, connect ChromaDB for self-hosted vector search, or use Pinecone for managed vector search.

Internal Model API Gateway

Let users create personal API keys and call admin-approved models through OpenAI-compatible API endpoints.

Enterprise Identity

Use Better Auth with users, admins, roles, organizations, teams, invitations, SSO, OAuth/OIDC, and SCIM.

Audit and Compliance Evidence

Track audit events, GDPR requests, ISO 27001/SOC 2 controls, retention notes, and CSV exports.

Air-Gapped Deployment

Deploy with Docker, local files, SQLite, PostgreSQL, MySQL, and ChromaDB profiles for enterprise environments.

Get Started

Quick start for local development

Batuk runs as a Next.js app. The fastest local path uses local JSON product data, SQLite auth, and either Ollama or a hosted provider configured from Settings.

Install dependencies with npm install.
Start the dev server with npm run dev.
Open http://localhost:3000.
Create a local account.
Choose a provider and model in Settings.
Start chatting, then enable Documents, Skills, Agents, or Audit as needed.

npm install
npm run dev

# Optional local model runtime
ollama pull llama3.1
ollama serve

Compare

Batuk comparisons

See how Batuk stacks up before you deploy.

Review production-grade Batuk comparisons for RAG privacy, API gateway controls, admin management, token analytics, audit evidence, deployment, and provider coverage.

All comparisons

Batuk vs

Open WebUI

Compare Batuk and Open WebUI for enterprise AI chat, RAG privacy, model routing, API keys, audit, admin controls, MCP, and self-hosted deployment.

Read comparison

Batuk vs

AnythingLLM

Compare Batuk and AnythingLLM across local AI, document chat, agents, vector databases, API access, enterprise controls, RAG privacy, and model gateway use cases.

Read comparison

Batuk vs

LibreChat

Compare Batuk and LibreChat for multi-model chat, agents, RAG, MCP, API access, enterprise admin, workspace privacy, compliance, and deployment.

Read comparison

Batuk vs

Langdock

Compare Batuk and Langdock for enterprise AI adoption, model choice, RAG, agents, workflows, APIs, deployment, compliance, and data control.

Read comparison

Concepts

Core product concepts

Provider

The model backend selected for a chat request: Ollama, OpenAI, OpenRouter, Claude, Grok, Sarvam AI, or custom compatible.

Document Chat

A top-bar mode that retrieves indexed document chunks from the signed-in user's personal scope or the selected shared workspace.

API Model Route

An admin-managed public API model ID that maps external clients to an approved provider, model, and base URL.

Personal API Key

A user-owned Batuk key for programmatic access. The raw secret is shown once and only a hash is persisted.

Skill

A reusable instruction package with description, examples, resources, and enabled state.

Agent Workflow

A saved chain of agents where each agent receives prior output and passes the next handoff forward.

Organization

An enterprise boundary for teams, members, roles, branding, admin pages, token usage, and scoped product data.

Shared Workspace

An admin-created collaboration scope where invited users can access workspace chats and workspace RAG without mixing data into personal context.

Audit Event

A compliance record for access, admin, document, privacy, and product actions.

Architecture

How Batuk is structured

Next.js App Router provides UI screens and API routes.
React components handle chat, settings, documents, enterprise admin, audit, Skills, and Agent Builder workspaces.
Provider adapters normalize model requests and streaming behavior.
API gateway modules authenticate hashed user keys, resolve admin-enabled model routes, return OpenAI-compatible responses, and record API token usage.
RAG modules extract files, chunk text, embed chunks, and query the active vector store.
Better Auth handles accounts, sessions, organizations, teams, admin APIs, OAuth/OIDC, SSO, and SCIM.
Product data stores can be JSON, SQLite, PostgreSQL, or MySQL depending on deployment needs.

app/
  api/
  ai-lab/
components/
  chat/
  docs/
  enterprise/
  audit/
hooks/
lib/
  auth*
  rag*
  product-data-store.js
database/
scripts/

Configure

Environment configuration

For local evaluation, most settings can be supplied through the UI. For enterprise deployment, use `.env.enterprise.example` as the canonical starting point. Keep one product data provider and one Better Auth database provider active at a time.

Variable	Values	Purpose
BATUK_DATA_STORE_PROVIDER	json \| sqlite \| postgresql \| mysql	Selects where Batuk product data is stored.
BATUK_DATA_DIR	Path	Root directory for JSON stores and local runtime data.
BATUK_DOCUMENT_FILE_STORAGE_DIR	Path	Stores original uploaded RAG documents.
BATUK_BRANDING_FILE_STORAGE_DIR	Path	Stores organization logo uploads.
BATUK_VECTOR_STORE_PROVIDER	json \| chroma \| pinecone	Selects vector database mode for RAG.
BETTER_AUTH_DATABASE_PROVIDER	sqlite \| mysql \| postgresql \| mssql \| mongodb	Selects the Better Auth identity database adapter.
BETTER_AUTH_URL	URL	Public origin for auth callbacks and cookie handling.
BETTER_AUTH_SECRET	Secret	Session and auth signing secret. Required for production.
BETTER_AUTH_PROVIDER_MODE	oauth \| legacy-oidc	Controls OAuth/OIDC provider mode.
BATUK_AUDIT_ENABLED	true \| false	Controls local audit evidence capture.

Configure

Model providers

Batuk keeps the chat experience stable while providers change underneath. A team can run local models, hosted APIs, private gateways, or a mix of all three.

Provider	Role	Configuration	Notes
Ollama	Local/private inference	Base URL and installed model ID	Best for offline and private model runs.
OpenAI	Chat, embeddings, web search, realtime voice	Provider key and selected model	Required for OpenAI embeddings and Realtime voice.
OpenRouter	Routed model catalog	Provider key and model ID	Useful when teams want access to many hosted models.
Claude	Anthropic Messages API	Provider key and Claude model	Supports hosted Anthropic models.
Grok	xAI models	Provider key and model ID	Supports xAI chat workflows.
Sarvam AI	Indian-language optimized models	Provider key and Sarvam model	Useful for multilingual India-focused workflows.
Custom compatible	LM Studio, vLLM, llama.cpp, LiteLLM, gateways	Base URL, model ID, optional key	Use for private model routers or local OpenAI-compatible servers.

Configure

RAG and vector databases

RAG starts in the Documents workspace. Batuk stores original uploads locally, extracts text, chunks content, computes embeddings, writes vectors, and retrieves matching chunks when Document Chat is enabled.

Supported uploads: PDF, TXT, Markdown, JSON, LOG, CSV, XLS, XLSX, and DOCX.
Local embeddings use deterministic 384-dimensional vectors for private indexing.
OpenAI embeddings use text-embedding-3-small with 1536 dimensions.
Local JSON vectors require no external service.
ChromaDB works as a self-hosted vector store.
Pinecone works as a managed vector store and handles dimension-specific indexes.
Download always serves the original uploaded file.
Delete removes local files, metadata, chunks, and remote vectors when applicable.

# Local JSON vectors
BATUK_VECTOR_STORE_PROVIDER=json
BATUK_LOCAL_VECTOR_DIR=/app/data/vectors

# ChromaDB
BATUK_VECTOR_STORE_PROVIDER=chroma
CHROMA_URL=http://chroma:8000
CHROMA_COLLECTION=sb_chat_documents

# Pinecone
BATUK_VECTOR_STORE_PROVIDER=pinecone
PINECONE_INDEX=sb-chat-documents
PINECONE_NAMESPACE=documents

Configure

Storage options

Batuk separates identity storage, product data, source files, branding assets, and vectors. This lets a small local install stay simple while enterprise deployments use durable databases and mounted volumes.

Layer	Default	Enterprise Options	Stores
Auth DB	SQLite	SQLite, MySQL, PostgreSQL, MS SQL, MongoDB	Better Auth users, sessions, accounts, organizations, teams, OAuth/OIDC, SSO, and SCIM.
Product data	Local JSON	SQLite, MySQL, PostgreSQL	Chats, folders, workspaces, documents metadata/chunks, memories, API management records, skills, agents, workflows, branding, token usage, compliance, and audit trails.
Documents	Local files	Configurable local/container path	Original uploaded files used for download and reindex operations.
Branding	public/branding	Configurable local/container path	Organization logos and whitelabel assets.
Vectors	Local JSON	ChromaDB, Pinecone	Document chunk embeddings for RAG retrieval.

Configure

Authentication and identity

Email/password accounts and HTTP-only sessions are enabled through Better Auth.
Admin plugin supports users, global roles, bans, password resets, and admin APIs.
Organization plugin supports organizations, members, invitations, teams, and org roles.
OAuth Provider mode supports OAuth 2.1 and OIDC through the openid scope.
Legacy OIDC mode remains available only for older client compatibility.
SSO supports enterprise OIDC/SAML providers.
SCIM supports identity-provider provisioning when configured.

npm run auth:migrate

# Auth adapters
sqlite
mysql
postgresql
mssql
mongodb

Configure

API access and model gateway

Batuk can operate like an internal OpenRouter-style gateway. Admins decide which provider/model routes are exposed, while each user creates their own API key for programmatic access.

Capability	Behavior
User API keys	Every signed-in user can create a personal Batuk key, copy the secret once, and revoke it later.
Secret storage	Raw API keys are never stored. Batuk stores a SHA-256 hash, a display preview, status, owner metadata, and timestamps.
Admin controls	Admins can review all user keys, revoke individual keys, revoke all API access for a user, and manage public model routes.
Model routes	Admins map public model IDs to provider, underlying model, base URL, and enabled state.
Compatible endpoints	Clients call GET /api/v1/models and POST /api/v1/chat/completions with Authorization: Bearer batuk_...
Usage tracking	API requests are recorded with source api, user, API key ID, public model ID, provider, tokens, and timestamps.

# List admin-enabled models
curl -H "Authorization: Bearer batuk_..." \
  http://localhost:3000/api/v1/models

# Create a chat completion
curl -X POST http://localhost:3000/api/v1/chat/completions \
  -H "Authorization: Bearer batuk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "batuk/qwen3-8b",
    "messages": [
      { "role": "user", "content": "Hello" }
    ]
  }'

Use

Chat workspace

Streaming

Assistant responses stream into the chat UI where supported by the provider.

Markdown

Messages render Markdown and GitHub-flavored tables/lists through react-markdown and remark-gfm.

Temporary Chat

Temporary conversations are visibly marked and not written to the saved chat history.

Folders

Chats can be organized into workspaces and folders, searched, imported, exported, and continued later.

Guardrails

Safer request screening and system behavior can be enabled while raw model mode remains available.

New Chat

New Chat returns users to the main chat window and opens a fresh conversation from any screen.

Use

Documents workspace

Upload files into the document library.
Search the document list by name or metadata.
Download the original uploaded file.
Delete documents and clean up vectors.
Reindex documents after changing embedding mode, chunk size, vector store, or provider settings.
Toggle Document Chat from the top bar when answers should be grounded in indexed files.

Use

Skills dashboard

Skills are reusable instructions that can travel with future chats. They are useful for house style, code review rules, domain response patterns, compliance checklists, and repeated workflows.

Create, update, delete, enable, and disable Skills.
Search Skills by name.
Store name, description, instructions, examples, resources, and timestamps.
Import and export the full Skills library as JSON.
Inject enabled Skills into chat requests as system context when relevant.

Use

Agent Builder

Create saved multi-agent workflows.
Add draft agents or insert reusable saved agents.
Write a separate instruction prompt for each agent.
Attach documents to Agent 1 so extracted file content starts the chain.
Run the chain sequentially, with each output passed to the next agent.
Review the visualizer and run trace before returning the final result to chat.

Agent 1 -> Extract facts
Agent 2 -> Reason over constraints
Agent 3 -> Produce final answer

Final output -> Chat window

Use

Voice and web search

Realtime Voice

Batuk creates OpenAI Realtime browser sessions through a server endpoint, streams microphone audio, receives spoken replies, and inserts transcripts into chat.

Hosted Web Search

OpenAI hosted web search can be enabled from the composer when current external context is required. It is optional and provider-specific.

Operate

Enterprise administration

First signed-in user can claim owner when no owner/admin exists.
Admins can create users by entering details manually.
Admins can update names, emails, and roles.
Admins can reset passwords, ban users, unban users, and delete users.
Admins can create organizations and switch active organization.
Admins can create teams, invite members, and manage member roles.
Admins can create, rename, configure, and delete shared workspaces.
Admins can add workspace members by email and remove members from a workspace member list.
Admins can manage API model routes and revoke individual or user-wide API access.
Non-admin users do not see Workspace Management, Enterprise Management, or Audit and Compliance menu entries.
Protected APIs enforce role-based permissions for product operations.

Operate

Token usage dashboard

Token usage is now an operations dashboard, not just a running total. Chat and API traffic are separated so admins can inspect product adoption, cost drivers, and high-volume integrations.

Dimension	What it shows
Channel	Separates chat requests from API requests.
User	Aggregates usage by signed-in user ID or email.
Chat	Tracks usage by chat ID for saved conversations and unsaved-chat for unsaved chat traffic.
API key	Tracks API usage by key ID so admins can inspect programmatic adoption and revoke risky access.
Provider/model	Shows usage by provider and public model ID.
Time	Rolls usage up by day, month, and year with numeric totals and lightweight charts.

recordTokenUsage({
  source: "api",       // or "chat"
  userId,
  userEmail,
  chatId,
  apiKeyId,
  apiModel,
  provider,
  model,
  inputTokens,
  outputTokens,
  totalTokens
})

Operate

Workspace privacy model

Personal chats, folders, uploaded documents, memories, and local JSON stores are scoped to the signed-in user.
A user's personal RAG context is not visible to other organization members.
Shared workspace data uses a separate workspace scope and is only available to admins or users added to that workspace.
Shared workspace RAG retrieves only vectors tagged for that workspace, so personal and workspace vector data do not mix.
Users only see shared workspaces where they are members; if none exist, the UI clearly states that they are not part of any workspace.
Deleting personal chats affects only the signed-in user's personal workspace.
Shared workspace chats can be deleted by admins and users who belong to that workspace.
Deleting a shared workspace removes its shared RAG metadata, local uploaded files, JSON chunks, and remote ChromaDB/Pinecone vectors when metadata is available.

Operate

Audit, GDPR, ISO 27001, and SOC 2 evidence

The Audit workspace is an evidence and operations surface. It helps teams capture product-level compliance records, but it does not replace legal review, organizational policy, or a formal certification process.

Audit trail with protected access, admin, privacy, document, and chat-library events.
Hash-chain fields for integrity evidence.
GDPR export, request, and erasure workflows.
Control register for GDPR, ISO 27001, and SOC 2 evidence mapping.
Data inventory and retention notes.
CSV audit export for review.

BATUK_AUDIT_ENABLED=true
BATUK_AUDIT_RETENTION_DAYS=365
BATUK_AUDIT_HASH_IDENTIFIERS=true
BATUK_AUDIT_MAX_EVENTS=10000

Operate

Organization whitelabeling

Editable

Product display name, tagline, uploaded logo, logo initials, accent color, and optional organization-name chip.

Locked

Footer attribution stays fixed as Batuk, created by Suhas Bhairav.

Storage

Branding settings are organization-scoped and stored in JSON or SQL product data.

Logo files

Uploaded logos are stored in the configured branding file storage directory.

Deploy

Docker and air-gapped deployment

Docker Compose keeps optional infrastructure behind profiles. This lets operators test JSON/SQLite locally, then switch to PostgreSQL, MySQL, or ChromaDB by editing the env file and enabling the matching profile.

batuk service builds the Next.js app container.
postgres profile starts PostgreSQL 16 and initializes SQL files.
mysql profile starts MySQL 8.4 and initializes SQL files.
chroma profile starts a ChromaDB vector service.
batuk_data volume stores JSON, SQLite, product data, and uploaded documents.
batuk_branding volume stores uploaded whitelabel logos.

cp .env.enterprise.example .env.enterprise

# Local JSON + SQLite auth
docker compose up --build

# PostgreSQL
docker compose --profile postgres up --build

# MySQL
docker compose --profile mysql up --build

# PostgreSQL + ChromaDB
docker compose --profile postgres --profile chroma up --build

Reference

Operational checklist

Before launch

Set production URL, rotate secrets, configure HTTPS, choose storage, configure backup, validate env, run migrations, and test auth flows.

Backups

Back up SQL databases, JSON data, uploaded documents, branding assets, audit records, and vector indexes.

Security

Use least privilege, secret management, network allow lists, role-based admin access, and provider key rotation.

Monitoring

Track app logs, auth failures, audit denials, document indexing failures, token usage, DB health, vector DB health, and storage volume growth.

Support

Troubleshooting

Pinecone dimension mismatch

Local embeddings are 384 dimensions and OpenAI embeddings are 1536 dimensions. Batuk creates dimension-specific sibling indexes when an existing Pinecone index uses the wrong dimension.

Document download fails

Confirm the original file still exists in BATUK_DOCUMENT_FILE_STORAGE_DIR or the mounted Docker data volume.

Logo upload returns JSON parse errors

Confirm upload responses are valid JSON and that BATUK_BRANDING_FILE_STORAGE_DIR is writable by the app container.

SSO or OIDC callback fails

Confirm BETTER_AUTH_URL, callback URLs, trusted client JSON, issuer metadata, and public origin match the deployed host.

ChromaDB connection fails

Confirm the chroma profile is running and CHROMA_URL points to the reachable service URL from the Batuk container.

Docker starts before DB is ready

The entrypoint retries migrations. Tune BATUK_STARTUP_RETRY_ATTEMPTS and BATUK_STARTUP_RETRY_SECONDS for slower enterprise databases.

FAQ

Frequently asked questions

What is Batuk?

Batuk is an open-source Sovereign AI chat workspace for teams. It lets users chat with local, hosted, and private model providers while adding RAG, agents, enterprise auth, audit, and deployment controls.

Is Batuk an Open WebUI alternative?

Yes. Batuk is an Open WebUI-style alternative built with Next.js and JavaScript, focused on model choice, readable architecture, RAG, enterprise identity, local-first storage, and self-hosted deployment.

Does Batuk require OpenAI?

No. Batuk supports Ollama and custom OpenAI-compatible endpoints. OpenAI is optional for OpenAI chat models, hosted web search, OpenAI embeddings, and Realtime voice.

Can Batuk run air-gapped?

Yes, for local models, local files, local JSON or SQL storage, and ChromaDB. Hosted model APIs and Pinecone require a network path unless the enterprise provides private connectivity.

Where are documents stored?

Original uploaded documents are stored in the configured document file storage directory. Personal document metadata, chunks, and vectors are scoped to the signed-in user. Shared workspace documents use a separate workspace scope.

Can users call Batuk programmatically?

Yes. Users can generate personal Batuk API keys and call admin-enabled models through OpenAI-compatible endpoints for model listing and chat completions.

Are API keys stored in the database?

Raw API keys are not stored. Batuk stores a SHA-256 hash, a short preview, status, owner metadata, and timestamps. The full key is shown once at creation.

Can admins revoke API access?

Yes. Admins can revoke individual API keys or revoke all active API access for a selected user.

Does Batuk support admins and teams?

Yes. Batuk uses Better Auth Admin and Organization features for users, roles, organizations, teams, members, invitations, and first-owner bootstrap.

Can non-admins see enterprise management pages?

No. Non-admin users can use their own API access, personal chat, documents, and shared workspaces they belong to, but they do not see Workspace Management, Enterprise Management, or Audit and Compliance menu entries.

Does Batuk certify GDPR, ISO 27001, or SOC 2 compliance?

No product can grant certification alone. Batuk provides product-level evidence workflows, audit trails, GDPR request operations, and control mappings. Formal certification requires organizational controls and auditor review.

Batuk guides

Explore Batuk or read the source.

Use the AI Lab page for product context, or open the repository when you are ready to deploy, customize, or extend Batuk.

Batuk page Repository

What Batuk is for

Chat With Any Approved Model

Document Chat and RAG

Vector Store Choice

Internal Model API Gateway

Enterprise Identity

Audit and Compliance Evidence

Air-Gapped Deployment

Quick start for local development

Batuk comparisons

See how Batuk stacks up before you deploy.

Open WebUI

AnythingLLM

LibreChat

Langdock

Core product concepts

Provider

Document Chat

API Model Route

Personal API Key

Skill

Agent Workflow

Organization

Shared Workspace

Audit Event

How Batuk is structured

Environment configuration

Model providers

RAG and vector databases

Storage options

Authentication and identity

API access and model gateway

Chat workspace

Streaming

Markdown

Temporary Chat

Folders

Guardrails

New Chat

Documents workspace

Skills dashboard

Agent Builder

Voice and web search

Realtime Voice

Hosted Web Search

Enterprise administration

Token usage dashboard

Workspace privacy model

Audit, GDPR, ISO 27001, and SOC 2 evidence

Organization whitelabeling

Editable

Locked

Storage

Logo files

Docker and air-gapped deployment

Operational checklist

Before launch

Backups

Security

Monitoring

Troubleshooting

Pinecone dimension mismatch

Document download fails

Logo upload returns JSON parse errors

SSO or OIDC callback fails

ChromaDB connection fails

Docker starts before DB is ready

Frequently asked questions

What is Batuk?

Is Batuk an Open WebUI alternative?

Does Batuk require OpenAI?

Can Batuk run air-gapped?

Where are documents stored?

Can users call Batuk programmatically?

Are API keys stored in the database?

Can admins revoke API access?

Does Batuk support admins and teams?

Can non-admins see enterprise management pages?

Does Batuk certify GDPR, ISO 27001, or SOC 2 compliance?

Read more about Batuk