Home / Docs

Getting Started with Zubo

Zubo is a self-hosted AI agent with persistent semantic memory, multi-channel presence across Telegram, Discord, Slack, WhatsApp, Signal, and Web Chat, 20+ smart built-in tools, sub-agent delegation, and workflow automation. It runs entirely on your machine — your data never leaves your infrastructure. Whether you need a personal assistant that remembers everything, an automation hub that connects your services, or an AI copilot embedded in every chat platform you use, Zubo handles it from a single process with a single configuration file.

Features

AI Engine

Channels

Memory

Tools

Skills

Agents

Workflows

Integrations

Scheduling

Voice

Dashboard

Budget & Cost Controls

Security

Installation

Choose the installation method that fits your platform.

macOS & Linux

Zubo requires Bun v1.0+ as its runtime. If you do not have Bun installed, visit bun.sh and run the one-line installer.

One-liner (recommended):

curl -fsSL https://zubo.bot/install.sh | bash

This installs Bun (if needed), installs Zubo globally, and runs the setup wizard automatically.

Manual install:

# Using Bun (recommended)
bun add -g zubo

# Or using npm
npm i -g zubo

# Then run the setup wizard
zubo setup

Windows (via WSL)

Zubo runs on Windows through the Windows Subsystem for Linux (WSL). This gives you full compatibility with zero workarounds.

Step 1: Install WSL (requires Windows 10 version 2004+ or Windows 11):

wsl --install

Restart your computer when prompted. This installs Ubuntu by default.

Step 2: Open the Ubuntu terminal from the Start Menu and install Zubo:

curl -fsSL https://zubo.bot/install.sh | bash

That's it. Zubo runs inside WSL with full access to all features. The web dashboard is accessible from your Windows browser at http://localhost:3000.

Docker

Run Zubo as a container with no local dependencies.

# Clone the repo
git clone https://github.com/apwn/zubo.git && cd zubo

# Copy the example env and add your API key
cp .env.example .env

# Start Zubo
docker compose up -d

The container exposes port 8787 for the web dashboard and mounts ~/.zubo for persistent data. Stop with docker compose down.

To configure, edit .env or mount your own config.json:

volumes:
  - ~/.zubo:/root/.zubo
  - ./my-config.json:/root/.zubo/config.json

The Setup Wizard

After installing (on any platform), run the setup wizard:

zubo setup

The interactive setup wizard walks you through initial configuration. It will:

Starting Zubo

# Start in foreground (logs to stdout)
zubo start

# Start as a background daemon
zubo start --daemon

When started, Zubo initializes the SQLite database, loads the embedding model, connects to all enabled channels, and starts the heartbeat scheduler. The web dashboard opens automatically in your default browser at http://localhost:3000 (or your configured port). When running with --daemon, Zubo writes its PID to ~/.zubo/zubo.pid and logs to ~/.zubo/logs/zubo.log.

Architecture

Zubo is a single-process application built around an event-driven agent loop. Here is a simplified view of how a message flows through the system:

                        +---------------------+
                        |    User Message      |
                        +----------+----------+
                                   |
                        +----------v----------+
                        |  Channel Adapter     |
                        |  (Telegram, Discord, |
                        |   Slack, WhatsApp,   |
                        |   Signal, Web Chat)  |
                        +----------+----------+
                                   |
                        +----------v----------+
                        |      Router          |
                        |  (auth, rate limit,  |
                        |   session lookup)    |
                        +----------+----------+
                                   |
                        +----------v----------+
                        |    Agent Loop        |
                        |                      |
                        |  +------+ +-------+  |
                        |  |Tools | |Memory |  |
                        |  +------+ +-------+  |
                        |  +------+ +-------+  |
                        |  |Skills| |Agents |  |
                        |  +------+ +-------+  |
                        |  +-----------+       |
                        |  |Scheduler  |       |
                        |  +-----------+       |
                        +----------+----------+
                                   |
                        +----------v----------+
                        |     LLM Provider     |
                        | (Claude / OpenAI /   |
                        |  Ollama / Groq ...)  |
                        +----------+----------+
                                   |
                        +----------v----------+
                        |      Response        |
                        +----------+----------+
                                   |
                        +----------v----------+
                        |  Channel Adapter     |
                        +----------+----------+
                                   |
                        +----------v----------+
                        |       User           |
                        +---------------------+

The Channel Adapter normalizes incoming messages from any platform into a unified internal format. The Router handles authentication, rate limiting, and session management. The Agent Loop is the core: it sends the conversation to the LLM, processes any tool calls the LLM requests, stores results in memory, and iterates until the LLM produces a final text response or the maximum turn count is reached. The response is then sent back through the Channel Adapter to the originating platform.

Directory Structure

All Zubo data lives under a single home directory, defaulting to ~/.zubo. You can override this with the ZUBO_HOME environment variable.

~/.zubo/
├── config.json          # Main configuration file
├── zubo.db              # SQLite database (WAL mode)
├── zubo.pid             # Daemon PID file (created on --daemon)
├── logs/
│   └── zubo.log         # Application logs (rotated daily)
├── sessions/
│   └── owner.jsonl      # Conversation history (JSON Lines)
├── models/
│   └── all-MiniLM-L6-v2/ # Embedding model (auto-downloaded on setup)
│       ├── model.onnx
│       ├── tokenizer.json
│       └── config.json
└── workspace/
    ├── SYSTEM.md         # Custom system prompt (editable)
    ├── MEMORY.md         # Persistent memory file
    ├── memory/           # Dated memory files (YYYY-MM-DD.md)
    ├── skills/           # User-installed skill files (.ts)
    ├── agents/           # Custom agent definitions (.json)
    ├── workflows/        # Workflow definitions (.json / .yaml)
    ├── teams/            # Team definitions (.json)
    ├── uploads/          # Uploaded and ingested documents
    └── backups/          # Daily SQLite backups (zubo-YYYY-MM-DD.db)

The config.json file is the single source of truth for all runtime configuration. The zubo.db SQLite database stores memory entries, embeddings, scheduled jobs, API keys, and analytics. Conversation history is stored as JSON Lines in the sessions/ directory for easy inspection and export.

Tech Stack

Component Technology
Runtime Bun
Language TypeScript
Database SQLite via bun:sqlite (WAL mode for concurrent reads)
Embeddings ONNX Runtime with all-MiniLM-L6-v2 (384 dimensions, ~80 MB)
Search Hybrid: FTS5 BM25 (40%) + cosine vector similarity (60%)
Dashboard Zero-dependency inline HTML (no build step, no CDN)
LLM SDK @anthropic-ai/sdk for Claude + OpenAI-compatible REST for all others
Channels Native API clients per platform (grammy, discord.js, @slack/bolt, whatsapp-web.js, signal-cli)
Voice OpenAI Whisper (STT), OpenAI TTS / ElevenLabs (TTS)

Best Practices

Next Steps

Now that you have Zubo installed and running, explore the rest of the documentation to unlock its full potential:

NextConfiguration →