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, Email, and Web Chat, 25+ smart built-in tools, MCP compatibility, 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.

Copy-Paste Task Cards

Secure API Access

Enable API auth and create a key before exposing ports beyond localhost.

zubo config set auth.enabled true
zubo auth create-key my-app

Set Local Model Fallback

Keep responses available during provider outages or API quota issues.

zubo config set failover '["openai","ollama"]'
zubo config set providers.ollama.model llama3.3

Common Errors

401 Unauthorized / Missing Bearer token

If auth.enabled is true, all /api/* calls require Authorization: Bearer <key>. Create a new key if needed.

curl -H "Authorization: Bearer YOUR_KEY" http://localhost:3000/api/dashboard/status
Provider Timeout / Upstream unavailable

Use failover and switch temporarily to a responsive provider or smaller model. Check logs for repeated timeout patterns.

zubo model openai/gpt-4o-mini
zubo logs --follow
Missing local model (Ollama/LM Studio)

If local providers fail, ensure the runtime is running and a model is installed.

ollama serve
ollama pull llama3.3

Start Here (10 Minutes)

  1. Run zubo setup and choose Quickstart for the fastest working config.
  2. Start the agent with zubo start, then open the dashboard at http://localhost:<port>.
  3. Set a budget guardrail early: zubo config set budget.dailyLimitUsd 5.
  4. Enable auth if exposed beyond localhost: zubo config set auth.enabled true then zubo auth create-key [label].

Next: read Configuration for defaults and safety settings, then CLI Commands for day-to-day operations.

Features

AI Engine

Channels

Memory

Tools

Skills

Personal Features

Agents

Workflows

Integrations

MCP (Model Context Protocol)

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

You'll be asked to choose between Terminal (classic prompts) or Dashboard (a browser-based wizard with visual provider cards, auto-detection, and connection testing). Both paths configure the same thing — pick whichever you prefer.

The wizard walks you through 4 steps:

The wizard also creates the ~/.zubo directory and all required subdirectories, generates your ~/.zubo/config.json file, and downloads the all-MiniLM-L6-v2 embedding model (~80 MB) for local semantic memory.

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.

Quick Start

Here is what Zubo looks like in action. These are real conversations showing key capabilities — memory, self-configuration, skill building, service integration, and scheduling.

Memory

You Hey, my name is Sarah and I work at Stripe on the payments team.
Zubo Got it, Sarah! Saved that to memory. What can I help you with?
You What's my name?
Zubo You're Sarah — you work at Stripe on the payments team.

Self-Configuration

You Switch to GPT-4o
Zubo Done — switched your active provider to OpenAI (gpt-4o). Takes effect on next restart.
You Set my daily budget to $5
Zubo Updated your daily limit to $5.00 USD. I'll pause requests when you hit the cap.

Building a Skill on the Fly

You Build me a tool that checks if a website is up
Zubo Created skill "website_checker"! It pings any URL and returns the status code and response time. Try it: "check if google.com is up"

Connecting a Service

You Connect my GitHub
Zubo I need a Personal Access Token (PAT). Go to GitHub → Settings → Developer settings → Personal access tokens → Generate new token. Need scopes: repo, read:org. Paste the token here.
You ghp_abc123...
Zubo Stored your GitHub token and installed 4 GitHub skills (issues, PRs, repos, commits). Try: "list my open PRs"

Scheduling

You Remind me in 30 minutes to review the PR
Zubo Reminder set! I'll ping you at 3:45 PM with: "Review the PR"
You Every weekday at 9am, send me a summary of my calendar
Zubo Scheduled "morning-briefing" — runs every weekday at 9:00 AM.

How Zubo Thinks

Zubo is not a chatbot that describes what it could do. It is an agent that acts. Here is the core behavior model that drives every interaction:

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, Email,     |
                        |   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 →