Documentation

Overview

EnzoAI is a self-hosted, local-first AI assistant. It runs models on your own hardware through Ollama, and stores every conversation, memory and document in a SQLite database on your machine. There is no EnzoAI cloud and no account with us.

You can use it three ways, all backed by the same server and the same data:

• Desktop app — an Electron tray app for Windows, macOS and Linux.
• Web UI — the same interface in a browser, useful for a NAS or server install.
• CLI — full terminal access, including an interactive chat session.

Connecting an external provider (OpenAI, Anthropic, Google) or a messaging platform (Telegram, Discord, Slack) is entirely optional and off by default.

Installation

Desktop app

Download the installer for your platform from the latest release. The app bundles everything it needs, including Ollama — you do not have to install a model engine separately.

Once running, EnzoAI lives in your system tray and serves the web UI at http://127.0.0.1:1616.

Docker (NAS, server, headless)

The image bundles Ollama, so a single container is all you need:

docker run -d \
  --name enzo-ai \
  -p 1616:1616 \
  -v enzo-data:/data \
  ghcr.io/eranabir/enzo-ai:latest

Then open http://<host>:1616. Mount /data on persistent storage — that volume holds the database, uploads and encryption keys.

First run

1. Create your account. The first account created becomes the administrator.
2. Pick a model. EnzoAI inspects your hardware (RAM, VRAM, GPU) and recommends a model that will actually run well on it, then downloads it for you.
3. Set up encryption (optional but recommended). See Encryption.
4. Start chatting.

Chat

The main view. Each chat keeps its own history, model and settings.

• Model picker — switch models per chat from the header. A chat attached to an agent always uses the agent's model.
• Attachments — send images to vision-capable models, or attach documents (PDF, Word, Excel, text); their text is extracted and included in the conversation.
• Project folder — attach a local folder to a chat to unlock list_directory and read_file scoped to that folder, and to use it as the default repository for the git tool.
• Message actions — copy, edit and resend, or retry any message.
• Failed replies — if a reply fails, the message is marked with an error and a retry button rather than disappearing.
• Thinking indicator — an animated indicator runs until the final answer arrives, including while tools are executing.

While a tool runs, its name appears inline in the reply (for example 🔧 dates) so you can see what the assistant actually did.

Memory

EnzoAI extracts durable facts about you from conversations and injects them into future chats, so you do not repeat yourself. Memories are typed as fact, decision, preference or work_context.

Only personal memories carry across chats. Per-chat working context stays in its own conversation, so unrelated chats do not bleed into each other.

Memory can be toggled per chat from the chat header, and reviewed or deleted at any time — in the UI, or with enzo-ai memories.

Agents

An agent is a saved assistant configuration: a persona plus the capabilities it is allowed to use. Open Agents in the sidebar to create one.

Writing good instructions

Put domain facts and tone in the instructions — the things only you know. You do not need to explain how to use tools: EnzoAI already tells the model that tool results are authoritative and must not be recalculated.

Credentials

Add an API key under an agent's Credentials, then reference it from the api_request tool as {{credential:NAME}} in a URL, header or body. The real value is substituted server-side, so the model never sees the secret.

Skills

A skill is a reusable set of instructions for one kind of task — “how we write a release note”, “how to summarise a lab report”. Write it once, attach it to as many agents as you like.

How they work

Skills load on demand. An agent only sees each skill's name and description up front; when a request matches, it calls the load_skill tool to pull in the full instructions and follows them. That means you can attach many skills without bloating every request.

Creating one

1. Open Skills in the sidebar and choose New skill.
2. Name — short and descriptive.
3. Description — one line. This is the part the agent reads to decide when the skill applies, so make it about the situation it covers.
4. Instructions — the full step-by-step guidance.

Then open an agent, pick the skill from the Skills dropdown, and save. An agent can hold several at once.

Knowledge bases

A knowledge base is a collection of documents the assistant can quote from. When one is attached to a chat or an agent, EnzoAI finds the passages most relevant to your message and adds them to the context — retrieval-augmented generation, entirely locally.

• Add documents as pasted text, a URL, or an uploaded file (PDF, Word, Excel, text).
• Documents are split into chunks and embedded with a local embedding model — no document ever leaves your machine.
• Attach a base to an agent (applies to all its chats) or to a single chat.

Manage bases under Knowledge in the sidebar, or with enzo-ai knowledge.

Tools

Tools let the assistant do things instead of guessing. An administrator enables tools system-wide; each agent then chooses which of the available ones it may use.

list_directory, read_file and load_skill appear automatically when their prerequisite exists; they are not toggles.

Tools require a model that supports function calling. Plain chats (no agent) only get tools if an administrator enables Tools in chats; agents always get theirs.

MCP servers

Model Context Protocol servers add third-party tools to EnzoAI. Add one under MCP Servers in the sidebar.

• stdio — a local command EnzoAI launches (with arguments and environment variables).
• http — a remote MCP endpoint.

Use test to connect and list the tools a server exposes before enabling it. Filesystem read/write access beyond a chat's attached folder is provided this way, via the Filesystem MCP connector, so you choose exactly which directory it may touch.

Connections

Connections let you talk to EnzoAI from a messaging platform. Each user configures their own bot, and an administrator can enable or disable each platform globally. Messages appear as normal chats in the app, and replies you send from the web UI are relayed back to the platform, so both sides stay in sync.

Telegram

1. Create a bot with @BotFather and copy the token.
2. Paste it under Settings → Connections → Telegram.
3. Message your bot, and send /chatid to get the chat ID used for scheduled agent delivery.

An allow-list of chat IDs controls who may talk to your bot.

Discord

Create an application and bot in the Discord developer portal, enable the message content intent, invite it to your server, and paste the bot token. For a channel ID, right-click a channel and choose Copy Channel ID.

Slack

Create a Slack app using Socket Mode — no public URL or tunnel required. You need a bot token and an app-level token. For a channel ID, copy the channel link and take the ID from the URL.

Your settings

Open Settings from your name in the sidebar footer.

• Profile — display name, nickname, and areas of expertise.
• About you and response style — added to the system prompt so replies are pitched at you and in the shape you prefer.
• Security — change your password, or set a PIN for quick unlock.
• Connections — your own Telegram, Discord and Slack bots, plus Google and Gmail accounts for the calendar and email tools.
• API keys — your own OpenAI, Anthropic or Google keys, if you want to use cloud models alongside local ones.

Admin panel

Available to administrators from the sidebar footer.

Context length

Controls how much conversation the model can hold at once (num_ctx). The default is 8192 tokens; the accepted range is 2048 to 131072.

Larger values let the model see more history and more retrieved documents, but use more memory — an oversized context on a large model can exhaust VRAM. EnzoAI applies the same value everywhere it talks to the model, which avoids needless model reloads.

Users & roles

EnzoAI is multi-user. Every user gets their own chats, memories, agents, skills, knowledge bases, connections and API keys — nobody can see anyone else's data.

• The first account created is the administrator.
• Administrators additionally manage models, system-wide tools, connections and other users.
• Each user connects their own messaging bots and cloud API keys.

Models

Local models run through Ollama and are managed from Admin → Models. EnzoAI scores models against your actual hardware and marks how well each will fit.

Models are labelled with the capabilities they support:

• Tools — supports function calling, which agents, tools and skills require.
• Vision — accepts images.
• Embedding — used for knowledge bases; hidden from chat pickers.

To use a cloud provider instead, add an API key for OpenAI, Anthropic or Google in your settings; its models then appear in the picker alongside local ones.

Encryption

EnzoAI can encrypt sensitive data at rest — API keys, bot tokens and agent credentials — using AES-256-GCM envelope encryption.

• Set it up once as an administrator. You choose a passphrase and receive a recovery key.
• The vault must be unlocked for the server to read protected values; while locked, chats stay inaccessible.
• The desktop app can unlock automatically at startup so the tray app just works.

Manage it from the admin panel or with enzo-ai vault.

CLI

The CLI is a standalone executable — no Node.js installation required. It ships with the desktop app and is attached to each release.

Point it at your server

enzo-ai config server http://127.0.0.1:1616
enzo-ai status

Use the same command with your NAS or server address for a remote install.

Sign in

enzo-ai login

This opens the web UI to approve the terminal session, so you never type your password into the shell. Use enzo-ai login -u <username> to sign in directly in the terminal instead.

Chat

# one-off question
enzo-ai chat "summarise today's git log"

# interactive session
enzo-ai chat

# resume an existing chat
enzo-ai chats list
enzo-ai chat -c <id>

CLI command reference

Every command supports --help. Destructive commands ask for confirmation unless you pass -y.

Architecture

• Server — NestJS, serving the API and the built web UI from one process on port 1616.
• Web — React and Vite.
• Desktop — Electron tray app wrapping the server, bundling Ollama.
• CLI — a standalone single-file executable.
• Storage — SQLite, alongside uploaded files, in your data directory.

EnzoAI is MIT licensed. The source is on GitHub.

Troubleshooting

No reply, or replies take a very long time

The first message after startup loads the model into memory, which can take a while on larger models. If it persists, check that the model fits your hardware and consider lowering the context length.

“Local model engine (Ollama) is not running”

The desktop app manages Ollama itself; restarting the app usually clears this. Do not run a second EnzoAI instance against the same model at the same time — loading a large model twice can exhaust GPU memory.

The assistant gives a wrong date or number

Check the agent has the dates and calculator tools enabled, and that its instructions do not forbid tool use for the kind of question you are asking. With the tools available, EnzoAI requires the model to report the tool's result exactly.

Tools or skills are missing from an agent

They need a model that supports function calling — check the model's badges under Admin → Models. Also confirm the tool is enabled system-wide in Admin → Tools, and that any account it depends on is connected.

The CLI cannot reach the server

Run enzo-ai status and confirm the URL with enzo-ai config show. For a NAS or server install, set the address explicitly with enzo-ai config server http://<host>:1616.