FAQ
Short answers to the questions operators and integrators actually ask.
General
Section titled “General”Is Kazma production-ready?
Section titled “Is Kazma production-ready?”The core agent, swarm orchestration, HITL gates, gateways, and chat memory (V2 cognitive engine — bi-temporal beliefs + per-turn PPR recall + auto-store) are implemented and wired. Install pip install -e ".[rag]" for full vector recall. Treat the safety layer as production-grade; memory is production-usable on single-node with health monitoring (see Memory & RAG).
What language is the UI in by default?
Section titled “What language is the UI in by default?”Arabic, RTL (agent.language: ar, agent.rtl: true). Set to en for English. The kazma-lang cookie switches per-browser without a restart.
What’s “Kazma” mean?
Section titled “What’s “Kazma” mean?”Kazma in Latin script; Arabic brand كاظمه (preferred) or كاظمة. The spelling كازما is wrong. The Majlis protocol (majlis.py) implements Gulf Arabic conversational rhythms.
Is web live voice a phone-call (duplex)?
Section titled “Is web live voice a phone-call (duplex)?”The Live button runs live voice on /ws/voice: same LangGraph brain, same
chat thread/journal as typed messages, and you can interrupt while it talks.
TTS speaks only the final reply, one sentence clip at a time. Typed web
chat does not auto-play TTS — click 🔊 on the message. With LiveKit
configured (LIVEKIT_URL + API key/secret) the browser also gets WebRTC
echo cancellation and TTS is published into the room. Telegram/Discord/Slack
stay voice notes (tts_reply only after a voice inbound). See Voice & media. OpenAI Realtime /
Gemini Live are not used as the brain (and are skipped as codecs).
API keys stay on Settings → Providers; Whisper is picked on Settings → Voice,
not as the active chat model.
Does "barcode" pick the coding model?
Section titled “Does "barcode" pick the coding model?”No. Classification uses word boundaries. An explicit
models.defaults.code (Settings → Models) wins over keyword routing.
KAZMA_MODEL still wins over both.
Can an MCP server make Kazma call the LLM (sampling)?
Section titled “Can an MCP server make Kazma call the LLM (sampling)?”Not automatically. Default off (KAZMA_MCP_SAMPLING). When on, you get a
HITL Once card; the sample call has no tools. Resource reads are fenced.
See Skills, MCP & tools.
Can I run the agent without the web server?
Section titled “Can I run the agent without the web server?”Yes. kazma ask "…" runs the LangGraph supervisor in-process (no uvicorn). Tokens stream to stdout; tool lines go to stderr. On a TTY, danger tools prompt y/N. Piped stdin / kazma ask - fail closed unless --yolo. Editors host Kazma with kazma acp (Agent Client Protocol: live session/update + session/request_permission). See Quickstart and CLI Reference.
How do I connect Gmail or Microsoft email?
Section titled “How do I connect Gmail or Microsoft email?”See Email integration. Sandbox works with no setup.
Settings → Email (/settings?tab=email) has a mode switcher per provider: OAuth | IMAP | POP.
| Provider | Recommended | Alternatives |
|---|---|---|
| Gmail | Browser OAuth (Gmail API) — Google Cloud OAuth Web client + Test user + gmail.modify scopes | IMAP/POP with a Google App Password (not your normal password) |
| Microsoft 365 | Browser OAuth (Graph) or device-code fallback | IMAP/POP to outlook.office365.com if the tenant still allows basic auth |
Mutating tools (email_send, email_delete, email_categorize) need HITL approval. If Gmail returns 403 insufficient scopes, add Gmail scopes on the OAuth consent screen, Disconnect, and Connect again.
How does Kazma tweet on X?
Section titled “How does Kazma tweet on X?”Official X API only — X publisher. Create a Read + Write app at developer.x.com, put the four OAuth 1.0a keys in Settings → X (not chat). Compose on X Studio (/x): Post now, Schedule, reschedule, thread hops, delete. Your click on that page is the approval. Chat tools (x_post, x_schedule_post, x_delete_post) still need a HITL card (YOLO cannot skip). All clocks on Studio opens /scheduled (cron + X together); the Studio planner is X-only. Kill-switch: KAZMA_X_POST=0.
Mentions / auto-reply is separate: X auto-reply. Start in draft mode, configure explicit subject targets and scoped positions, and review sources and typed checks in Conversations. Multiple/conflicting matches and incomplete evidence are held; stranger #Open markers cannot grant authority. Facts constrain the position. Unattended publishing needs a current human-reviewed bilingual qualification report; KAZMA_X_REPLY=0 disables replies.
How do I make the agent research the web?
Section titled “How do I make the agent research the web?”There is no /research slash command. Ask in chat (e.g. “Research X and cite sources”) or use /swarm research … for multi-worker dispatch. The agent uses web_search, read_url / read_url_to_file, optional crawl_site, and digest_research_file. See Web research.
Why is a long page truncated?
Section titled “Why is a long page truncated?”read_url returns a window (default 16k, env KAZMA_READ_URL_MAX_CHARS) and supports offset / max_chars paging. For the full page, use read_url_to_file then digest_research_file or read_research_chunk. Graph results for research tools allow a higher truncate cap (KAZMA_TOOL_RESULT_RESEARCH_MAX_CHARS).
How do I process PDFs / Office docs securely?
Section titled “How do I process PDFs / Office docs securely?”Use Document Intelligence — not a one-off script path:
- Web: open
/documents, upload, wait for stateready. - Agent:
document_import(workspace-safe path) →document_read/document_index. - Chat gateway:
/documents list|read|…(alias/docs).
Content is sniffed, parsed out-of-process, fenced for the LLM, and stored
content-addressed. PDFs with scripts, outside actions, attachments or links to
files and network shares are refused. The default worker is a child process
with memory and CPU limits but no filesystem or network confinement; for
documents you do not trust, run the container profile
(KAZMA_DOCUMENT_WORKER_ISOLATION=container: one container per job, no
network, no mounts). See Document Intelligence and
Document security.
What’s the difference between generate_pdf and document_import?
Section titled “What’s the difference between generate_pdf and document_import?”| Path | Skill / API | Stores |
|---|---|---|
| Simple / legacy | document-generator tools (generate_pdf, …) | Files under kazma-data/documents/ — no durable jobs/ACL |
| Platform | document-platform tools + /api/documents/* | Opaque IDs, jobs, tenants, restart-safe pipeline |
Prefer the platform for multi-user or production document work.
How do I index an uploaded file into Knowledge Library?
Section titled “How do I index an uploaded file into Knowledge Library?”After the document is ready: UI Index with a library_id, or
document_index / POST /api/documents/{id}/index. Auto-index is off by
default. Search with document_search or library tools. See
Knowledge Library — document bridge.
Why is convert / redact failing?
Section titled “Why is convert / redact failing?”Optional engines may be missing. Install pip install -e ".[document-platform]"
and check GET /api/documents/health (renderers/mutators readiness). API returns
truthful 422/503 when degraded. In the container worker profile the
engines are the worker image’s, not the host’s: the health check reports what
the image has, a broker that is not ready answers the retryable
worker_isolation_unavailable, and GET /api/documents/ops/readiness shows
document_worker_image_outdated when the image was built from other document
code than Kazma runs (rebuild it and restart the broker).
How do I enable malware scanning?
Section titled “How do I enable malware scanning?”Kazma does not install ClamAV with pip. It runs clamdscan when that program is on PATH, and clamscan otherwise. Settings → Documents sets the mode (auto, on, or off) and the fail-closed switch. Readiness reports malware.available.
With KAZMA_PRODUCTION=1, fail-closed is on. A missing scanner, a missing virus database, or a scanner error rejects the upload. A queued job is scanned again before it is parsed (today’s policy, not the one at upload); when that scan cannot run, the job is held and retried, then dead-lettered — never marked as unsafe content.
Linux and Docker. The image installs clamav and runs freshclam. On a host, install the distro ClamAV package and run freshclam once so clamscan has signatures.
Windows.
winget install --id Cisco.ClamAV -e --accept-package-agreements --accept-source-agreementsThe installer places clamscan.exe and clamdscan.exe in C:\Program Files\ClamAV and does not add that folder to PATH. Do not add the whole folder unless clamd is running. Kazma prefers clamdscan, and a daemon client with no daemon is a failed scan. Production then rejects the upload.
To use clamscan by itself:
- Create a
databasedirectory you can write, and afreshclam.confnext to the copy ofclamscan.exeyou will put onPATH. Writing those underC:\Program Files\ClamAVneeds an elevated shell. A copy under%LOCALAPPDATA%\ClamAVdoes not. freshclam.confmust not contain the sampleExampleline. SetDatabaseMirror database.clamav.netandDatabaseDirectoryto that database folder.- Run
freshclam.exe. It downloadsmain.cvd,daily.cvd, andbytecode.cvd. - Put
clamscan.exeand the DLLs from the install onPATH, with the database beside the executable (or a junction to it). Leaveclamdscan.exeoffPATH.
clamscan --no-summary on a small text file should print OK. Reload Kazma from a new terminal so the server process inherits the updated PATH. Readiness then shows malware.available true and scanner clamscan.
Providers & models
Section titled “Providers & models”Which LLM providers work?
Section titled “Which LLM providers work?”Ten presets ship: OpenAI, Anthropic, DeepSeek, Google Gemini (ADC), xAI, OpenRouter, Ollama, LM Studio, NVIDIA NIM, Custom. Any OpenAI-compatible endpoint works. See Configuration → provider presets.
Do I need LiteLLM?
Section titled “Do I need LiteLLM?”No. Kazma never import litellm. An optional proxy is enough: set
KAZMA_LITELLM_URL=http://127.0.0.1:4000 (or llm.gateway.url). Only
OpenAI-compatible providers (OpenAI, DeepSeek, Groq, NIM, …) go through it.
Anthropic / Azure / Bedrock / Gemini stay native. Local Ollama / LM Studio
stay direct unless KAZMA_LITELLM_LOCAL=1. Kill-switch: KAZMA_LITELLM=0.
You can still point a single provider’s base_url at the proxy instead.
Why doesn’t DEEPSEEK_API_KEY / ANTHROPIC_API_KEY work?
Section titled “Why doesn’t DEEPSEEK_API_KEY / ANTHROPIC_API_KEY work?”They’re in .env.example but no code reads them. Key those providers via the ConfigStore provider list or kazma.yaml. Only OPENAI_API_KEY and KAZMA_API_KEY are generic env-var fallbacks.
How do I switch models safely?
Section titled “How do I switch models safely?”Use set_active_model() (auto-switches provider) or the Web UI / POST /api/provider/switch. Never set model without provider — get_client() auto-corrects, but explicit is safer.
How do I use a local model?
Section titled “How do I use a local model?”Point the provider at Ollama (http://127.0.0.1:11434/v1) or LM Studio (http://localhost:1234/v1). No API key needed — dummy keys are injected automatically.
Memory & RAG
Section titled “Memory & RAG”Why doesn’t my agent remember things?
Section titled “Why doesn’t my agent remember things?”By default, memory is automatic:
- Per-turn RAG injects relevant past facts on every user message (
memory.per_turn_retrieval). - Auto-store writes durable user facts (and optional turn snapshots) after each reply (
memory.auto_store). - The LLM can also call
memory_store/memory_searchtools explicitly.
If recall is empty: install the RAG extra (pip install -e ".[rag]"), confirm Dashboard memory health is ACTIVE, and ensure memory.enabled is true (TUI Settings or kazma.yaml). See Memory & RAG.
Is the “4-layer memory” real?
Section titled “Is the “4-layer memory” real?”That was the V1 stack (UnifiedMemoryAdapter: Chroma L1 + graph L2 + FTS5 L3 + sqlite-vec L4, RRF-blended). V1 was removed in the V1→V2 cutover. The current and only stack is the V2 Cognitive Engine — bi-temporal belief graph + 4-tier episodes + Local Ego-Graph PPR recall (memory/recall.py:recall()). It is the chat default for per-turn recall, tools, auto-store, and compaction.
Do I need to install ChromaDB?
Section titled “Do I need to install ChromaDB?”V2 recall on one node uses sqlite-vec (bundled via the [rag] extra), not ChromaDB. When KAZMA_DATABASE_URL (or the memory state DSN) is set, dense search auto-selects pgvector (KAZMA_PGVECTOR=0 keeps sqlite-vec). Install pip install -e ".[rag]" for local embeddings (sqlite-vec + sentence-transformers; chromadb is still pulled in for embedder types and the semantic router). Without embeddings, V2 degrades to FTS5-only episode search; the Dashboard memory health board shows what is available.
Why is tiktoken mentioned if it’s not a dependency?
Section titled “Why is tiktoken mentioned if it’s not a dependency?”TokenCounter uses tiktoken if installed, else a chars/4 heuristic. Install it yourself (pip install tiktoken) for accurate counts.
Safety & HITL
Section titled “Safety & HITL”A danger tool executed without asking — why?
Section titled “A danger tool executed without asking — why?”Three things to check (see Troubleshooting §3):
- Was
hitl_configpassed to your graph build? (Custom builds viacreate_supervisor_graph()without it = dormant gate.) - Is the tool on the right danger list? (Three lists: yaml,
_EXTENDED_DANGER,classify_mcp_tool.) - Is
allow_headless_danger=Trueset? (Should beFalsein production.)
Do I need KAZMA_SECRET?
Section titled “Do I need KAZMA_SECRET?”Yes for any non-localhost deployment. It protects /api/approve. Without it, approval endpoints are unauthenticated. kazma serve only binds 0.0.0.0 when it’s set.
Are skills cryptographically signed?
Section titled “Are skills cryptographically signed?”Yes. kazma hub sign writes an HMAC-SHA256 signature; the loader verifies it fail-closed with hmac.compare_digest. See Skills, MCP & Tools.
Are MCP servers authenticated?
Section titled “Are MCP servers authenticated?”Only SSE transport (bearer/custom header). Stdio has no auth — sandbox it.
How do I run a multi-worker task?
Section titled “How do I run a multi-worker task?”kazma swarm dispatch researcher "summarize X"kazma swarm fanout --workers a,b,c --aggregation vote "question"kazma swarm pipeline --workers researcher,builder "build Y"Why did my handoff loop break with an error?
Section titled “Why did my handoff loop break with an error?”Handoffs are capped at depth 5 and 2 visits per worker (handoff_guards.py). A→B→A→B… is intentionally blocked. Legitimate A→B→A return handoffs work (2 visits allowed).
Is there Prometheus?
Section titled “Is there Prometheus?”No. Metrics are in-memory + SQLite. See Roadmap.
Deployment
Section titled “Deployment”Docker or bare metal?
Section titled “Docker or bare metal?”Docker Compose is the primary path. Bare kazma serve works for single-host dev. See Deployment.
Can I deploy on Cloudflare Pages / edge?
Section titled “Can I deploy on Cloudflare Pages / edge?”No. Kazma is a stateful Python service. Don’t attempt serverless packaging.
Is there a Kubernetes manifest?
Section titled “Is there a Kubernetes manifest?”No. The old kubernetes/ files described a separate Hub service this repo never built, and were removed. Deployment §4 lists what a manifest for the main agent needs.
Why does the container bind 0.0.0.0?
Section titled “Why does the container bind 0.0.0.0?”Required inside Docker so the published port reaches the service. Docker’s network isolation is the security boundary (explained in the Dockerfile comment). For bare metal, use 127.0.0.1 + a reverse proxy.
Concurrency
Section titled “Concurrency”I got “database is locked” — what now?
Section titled “I got “database is locked” — what now?”WAL + busy_timeout=5000 is set everywhere. You likely have a long write transaction or a second connection. Use batch_set() for multi-key writes and always use get_config_store(). See Troubleshooting §4.
Can I run multiple Kazma processes on the same DB?
Section titled “Can I run multiple Kazma processes on the same DB?”Not recommended. WAL allows one writer. If you scale horizontally, give each process its own kazma-data/ or shard by tenant.
Documentation audit notes
Section titled “Documentation audit notes”This FAQ reflects verified behavior. If an answer here contradicts older README text, this FAQ is the accurate one as of v0.9+.