Documentation · v0.3.0
Everything you need to install, configure and extend the open-source AI agent gateway.
Xavani is a local-first, open-source AI agent for terminal, desktop and messaging platforms. It can use files, shell commands, browsers, research tools, media tools, schedules and integrations. It also provides persistent memory, reusable skills, model-provider choice and isolated subagents. Xavani sends no product telemetry. Remote model and integration requests still follow the terms of the provider you configure. MIT-licensed and built by Enternovate.
$ curl -fsSL https://raw.githubusercontent.com/enternovate/xavani-agent/main/install.sh | bash$ iwr -Uri https://raw.githubusercontent.com/enternovate/xavani-agent/main/install.ps1 | iex$ git clone https://github.com/enternovate/xavani-agent.git && cd xavani-agent && pip install -e . && xavani1 · Install
Run the installer for your platform, then run: xavani setup && xavani doctor && xavani
2 · Add a provider key
Edit ~/.xavani/.env and add your key, e.g. OPENAI_API_KEY=sk-... (or any provider. See Providers)
3 · Start typing
Run xavani and start a conversation. Try /model to switch providers, /skills to browse reusable procedures, and /tools to inspect enabled tools.
4 · Go further
Configure messaging with xavani gateway setup, schedule work with xavani cron, or connect tools through MCP and plugins.
Give Xavani a concrete outcome and a way to verify it. State whether it may edit files, run commands or contact external services. For sensitive work, ask it to investigate without editing first and keep approvals enabled.
Audit this project, find why the smallest relevant test fails, fix the root cause, run the test, and explain the result.Install, configure one provider, and complete a small task with a clear pass condition.
Use /help, /model, /tools, /skills, /new and /resume inside an interactive session.
Resume sessions, save durable facts to memory, and turn repeated procedures into skills.
Add schedules, messaging gateways, MCP servers, plugins and isolated subagents only when the task needs them.
Run xavani setup to walk through the interactive wizard: provider keys, model choice, gateway channels and shell hooks. It writes your configuration to ~/.xavani/.env and ~/.xavani/config.yaml. After the wizard, run xavani config check to find missing or outdated values, then xavani doctor for a broader installation health check.
$ xavani setup$ xavani config check && xavani doctorA full AI assistant with built-in skills and context enrichment, running on supported providers or a local OpenAI-compatible endpoint.
A policy, auth, rate-limit and audit proxy for MCP servers. It exposes and governs tools on :8080 with a full audit trail.
Interoperability across MCP, A2A and OpenAPI so agents and applications can talk to each other regardless of protocol.
Episodic (FTS5) and procedural memory that persists across sessions. Pluggable backends include Honcho and Mem0.
OpenTelemetry traces and metrics with a local dashboard on :8081. See every tool call, token and cost.
Portable, reproducible agents defined in a single .agent.toml file. Version your agents like code.
Install MCP servers and tools from a security-scanned registry with one command (/install).
The CLI is a prompt_toolkit terminal app. Type /help in-session for the full list. Common commands:
/modelSwitch model or provider mid-session/tools, /toolsetsManage enabled tools/skillsBrowse and install skills/cronSchedule recurring jobs/configView configuration/voiceVoice mode (TTS/STT)/memoryPersistent memory across sessions/imageAttach an image/branch, /resumeFork or resume sessionsxavani gateway runRun the messaging gateway/installInstall an MCP server from the registry/skinChange the theme (dark blue buffalo default)Xavani works with virtually every major AI provider, global and Chinese, plus local models. Switch with /model at any time. Keys live in ~/.xavani/.env; configuration in ~/.xavani/config.yaml.
~/.xavani/.envAPI keys and secrets (never committed)
~/.xavani/config.yamlModels, providers, tools, approvals, memory
~/.xavani/skills/Installed and user-authored skills
~/.xavani/sessions/Session transcripts
~/.xavani/logs/Gateway and error logs
~/.xavani/auth.jsonOAuth tokens and credential pools
Switch provider or model mid-session with /model. Provider keys live in ~/.xavani/.env: OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, DEEPSEEK_API_KEY, XAI_API_KEY, OPENROUTER_API_KEY and more. For fully local inference, point Xavani at Ollama. The OpenAI-compatible endpoint works with any model you have pulled. The gateway and the CLI share the same credential pool.
Archived comparison
The archived guide highlighted GLM-5.3-Flash, not a current default. The 27 August 2026 source snapshot records an intelligence score of 57, a 1M context window and listed API prices of $0.15 input / $0.5 output per million tokens. These figures were not revalidated in this editorial update. Check the source and evaluate your own tasks before standardising.
Xavani reads environment variables for providers, tools, gateways and runtime controls. Provider examples include OPENAI_API_KEY and DEEPSEEK_API_KEY, alongside tool, gateway and proxy settings. The full auto-generated reference lives in the repo at docs/reference/env-vars.md.
XAVANI_HOMEAgent home directory (default ~/.xavani)
XAVANI_DISABLE_TELEMETRYForced on. Zero telemetry guarantee
DO_NOT_TRACKRespected at startup
OPENAI_API_KEY / ANTHROPIC_API_KEY / GEMINI_API_KEY / DEEPSEEK_API_KEY …Provider keys
XAVANI_ACCEPT_HOOKSAuto-approve unseen shell hooks
XAVANI_KANBAN_TASKSet for kanban worker tasks
The gateway runs Xavani on messaging platforms with configured tool access, not just chat. Configure it with xavani gateway setup, then run xavani gateway run or install the background service.
The MCP gateway exposes and governs MCP servers on port 8080. Every tool call passes policy, authentication, rate limits and a full audit trail. Install servers from the security-scanned registry with /install, or convert any OpenAPI specification into callable MCP tools. Agents and applications can use tools safely, with accountability.
Allow and deny rules per tool or server, enforced on every call.
Token-gated access with per-client limits.
Every tool call is logged with actor, timestamp and payload.
Schedule recurring jobs with /cron or the xavani cron commands. The scheduler is durable. Jobs survive restarts. Inspect the queue with xavani cron list and confirm the scheduler is running with xavani cron status.
Xavani keeps two kinds of memory across sessions: episodic memory (a local FTS5 index of what happened) and procedural memory (the skills it writes after solving hard problems). Manage it with /memory. Backends are pluggable: Honcho and Mem0 are supported. Local state remains on your machine. Content sent to a configured remote model, memory provider or integration follows that service's data-handling terms.
Skills are reusable procedures that Xavani loads on demand. Built-in and optional skills cover research, software delivery, media, infrastructure, productivity and integrations. Browse them with /skills or add a SKILL.md under ~/.xavani/skills/. Xavani can also maintain procedures that you explicitly choose to keep for later sessions.
Xavani Desktop v0.3.0 uses the same local Xavani home, configuration, sessions, skills and memory. It adds chat, Studio, files, tasks, terminal and live preview.
Published builds: macOS Apple Silicon and Windows x64. Preview builds are unsigned.
xavani.pyEntry point. CLI with the dark-blue buffalo skin, forces XAVANI_HOME + zero telemetrycli.pyThe interactive CLI corerun_agent.pyAIAgent. The conversation loop (LLM calls, tool dispatch)agent/Prompt builder, context compression, memory, model routing, credential pools, skill dispatchxavani_cli/CLI subcommands, config, skins, slash-command registrytools/One file per tool. Web, file, terminal, browser, image and moregateway/Messaging gateway with per-platform adapters (Telegram, Discord, Slack …)cron/Durable job schedulerskills/ and oag_skills/Bundled and optional skill packagesxavani_observability/Metrics collector, cost ledger, dashboard TUIxavani_memory/Episodic (FTS5) + procedural memoryxavani_wisdom/The Oracle. Consequence projection and downfall detectionNo analytics, no phone-home. XAVANI_DISABLE_TELEMETRY forced at startup.
Keys, sessions, memory and skills stay in ~/.xavani on your machine.
Free for any use; code you can read is code you can verify.
Security issues via the repo's SECURITY.md process.
Keep Xavani current with xavani update. It pulls the latest code, validates the critical entry files, refreshes pinned dependencies and clears the bytecode cache, with a safety rollback if anything fails to parse. Releases are tracked on the releases & changelog page and in the repository CHANGELOG.
$ xavani updateXavani sends no product analytics or phone-home telemetry. Local state stays in ~/.xavani. Requests sent to a remote model or connected service are subject to that provider’s data handling terms.
Xavani supports multiple direct, subscription and OpenAI-compatible providers, including local endpoints. Use /model or the model setup flow to inspect the providers available in your installed version.
A proxy that governs access to MCP servers with policy, authentication, rate limits and a full audit log. Agents can use tools safely, with accountability.
Xavani stores configuration, sessions, memory and skills under ~/.xavani by default. Content sent to a remote model or integration leaves the machine only for that configured request.
Yes. The gateway connects Telegram, Discord, Slack, WhatsApp, Signal, Matrix, email and more, with full tool access from chat.
MIT-licensed and free for any use. Built by Enternovate, derived from Hermes Agent by Nous Research (MIT).
This documentation is available in machine-readable form for LLMs and coding agents. Machine-readable indexes of every page and repository: