Self-host with Python

Run viora on your own server or laptop. Python 3.10 or newer.

Install

pip install viora-ai
# with Claude support:      pip install "viora-ai[anthropic]"
# with PDF reading:         pip install "viora-ai[pdf]"

On Linux distributions that protect the system Python (Arch, Ubuntu 24.04+, Debian 12+), pip install stops with "externally-managed-environment". Install the viora command with uv tool install viora-ai (or pipx install viora-ai), or install into a virtual environment: python -m venv .venv && . .venv/bin/activate && pip install viora-ai.

The package is called viora-ai on PyPI. You still import viora in Python, and the command is viora.

Create a profile

viora init

This asks a few simple questions (name, services, contacts, common questions, website pages to read) and saves viora.yaml. To start from a filled-in example instead: viora init --example.

Choose an AI provider

Put your settings in a .env file next to viora.yaml. The default is Cloudflare Workers AI, which has a free daily allowance:

VIORA_EMBEDDINGS=cloudflare
VIORA_CHAT=cloudflare
CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_API_TOKEN=token-with-workers-ai-permission
VIORA_ADMIN_KEY=a-long-random-secret

Other options, including fully local models with Ollama, are in AI providers.

Voice conversations use speech to text from the same provider: Whisper on Cloudflare Workers AI, or /audio/transcriptions on OpenAI and compatible servers. To choose it yourself, set VIORA_VOICE to cloudflare, openai or off (and optionally VIORA_VOICE_MODEL). With Ollama, Anthropic or the offline providers, voice is off unless you set it. Spoken answers in live voice use VIORA_SPEECH the same way (cloudflare for Aura-2 English voices, openai, or off), with VIORA_SPEECH_VOICE to pick a voice.

Build the knowledge base

viora ingest

viora reads your profile, files and website pages, splits them into passages and stores them in .viora/viora.db. Run it again whenever you change the profile.

Try it

viora ask "What are your opening hours?"
viora ask "Mnauza nini?"

Serve the widget

viora serve --port 8000

Then add the widget to your website, pointing at your server:

viora embed --url https://assistant.example.com
<script src="https://assistant.example.com/widget.js" data-api="https://assistant.example.com" data-site="your-site" async></script>

Put the server behind HTTPS (for example Caddy, nginx or a Cloudflare Tunnel). Interactive API docs are at /docs on your server.

See what visitors asked

viora questions          # questions it couldn't answer
viora questions --no-unanswered   # everything
viora leads              # contacts visitors left

Publish to viora cloud instead

Prefer not to run a server? Keep editing viora.yaml locally and publish it to viora cloud. Your computer reads the website pages and files, so the cloud gets the full text:

export VIORA_CLOUD_SITE=your-site-id
export VIORA_CLOUD_KEY=vk_...
viora push

Use it from Python

import asyncio
from viora import Viora, Profile, Settings
from viora.providers import make_chat, make_embedder
from viora.store import Store

settings = Settings()
engine = Viora(settings, Store(settings.db_path), make_embedder(settings), make_chat(settings))
asyncio.run(engine.index(Profile.load("viora.yaml")))
print(asyncio.run(engine.answer("your-site", "Do you offer school transport?"))["answer"])