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, over 35 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

• Multi-provider LLM support — Claude (Anthropic), OpenAI (GPT-4o, GPT-4-turbo), Google Gemini, Ollama (local models), Groq (fast inference), Together (open models), OpenRouter (multi-model gateway), DeepSeek, xAI (Grok), Fireworks, LM Studio (local GUI), and any OpenAI-compatible endpoint. Switch providers with a single config change.
• Smart routing — automatically routes simple queries to fast, cheap models and complex queries to more capable ones. Saves cost without sacrificing quality, with full manual override when you need it.
• Automatic failover — define an ordered list of backup providers. If the primary is down or rate-limited, Zubo seamlessly falls through to the next provider in the chain with no user-facing interruption.
• Streaming responses — token-by-token streaming for all providers that support it. Messages appear in real time across every channel.
• Context compaction — when the conversation approaches the context window limit, Zubo automatically summarizes older turns to free space while preserving critical details.
• 200k token context — supports the full 200,000 token context window on Claude models, with configurable context windows per provider.

Channels

• Telegram — full bot API integration with user allow-listing by numeric Telegram ID.
• Discord — bot presence in servers and DMs, with user allow-listing by Discord user ID.
• Slack — app-level integration using Bot Token and App Token, with user allow-listing by Slack member ID.
• WhatsApp — via the WhatsApp Web multi-device API, with phone number allow-listing.
• Signal — via signal-cli, with phone number allow-listing.
• Web Chat — built-in web dashboard with real-time chat, served on a configurable port.
• All channels share the same memory, personality, tools, and conversation history. A fact learned in Telegram is immediately available in Discord.

Memory

• Persistent semantic memory with vector embeddings powered by all-MiniLM-L6-v2 (384 dimensions), running locally via ONNX Runtime with zero external API calls.
• Full-text search using SQLite FTS5 with BM25 ranking for keyword-based retrieval.
• Hybrid search that combines 60% vector similarity (cosine) with 40% FTS5 BM25 scoring for best-of-both-worlds recall.
• Automatic chunking with overlap for long documents, ensuring context is preserved across chunk boundaries.
• Document ingestion supporting PDF, DOCX, TXT, CSV, JSON, YAML, and common code file formats. Upload a document and Zubo indexes it into searchable memory automatically.

Tools

• 35+ built-in tools including shell command execution, file I/O (read, write, list, search), web search (DuckDuckGo, Brave, Google), HTTP requests, memory read/write/search, secrets management, and cron job scheduling.
• Tools are permission-gated with three levels: safe, sensitive, and dangerous. Dangerous operations require explicit confirmation tokens.

Skills

• Extensible single-file TypeScript skills that you can write, install, or share. Each skill is a self-contained .ts file with a manifest header.
• Hot-reload without restart — drop a skill file into ~/.zubo/workspace/skills/ and it becomes available immediately.
• Community skill registry for discovering and installing skills built by others.
• Skill sandboxing — user-installed skills run in isolated subprocesses with configurable timeouts, preventing runaway code from affecting the main process.

Agents

• Custom sub-agents with focused system prompts, restricted tool access, and specialized behavior. Define a “code-reviewer” agent that only has access to file and git tools, or a “researcher” agent that only has web search.
• 2-level delegation — the main agent can delegate tasks to sub-agents, which can in turn delegate to their own sub-agents, up to two levels deep.

Workflows

• Multi-agent pipelines with dependency resolution, parallel execution of independent steps, and variable passing between stages.
• Define workflows as JSON or YAML in ~/.zubo/workspace/workflows/ and trigger them by name or on a schedule.

Integrations

• GitHub — repositories, issues, pull requests, code search, commit history.
• Google — Calendar (read/write events), Gmail (read/send), Sheets (read/write), Docs (read), Drive (list/search/download).
• Notion — pages, databases, blocks.
• Linear — issues, projects, teams.
• Jira — issues, projects, sprints.
• Slack — channels, messages, users (beyond the chat channel).
• Twitter — post tweets, read timelines.

Scheduling

• Natural language scheduling — describe schedules in plain English like “every weekday at 9am” or “twice a day”. Zubo parses natural language into cron expressions automatically.
• Cron jobs supporting any standard cron expression (e.g., 0 9 * * 1-5 for weekday mornings).
• Configurable heartbeat from 1 to 1440 minutes (default 30), where Zubo wakes up, checks for pending tasks, processes scheduled jobs, and optionally sends proactive messages.
• Proactive memory-based triggers — Zubo can surface reminders and follow-ups based on things it has remembered.
• Morning briefing — a built-in scheduled task that summarizes your calendar, pending tasks, and unread messages each morning.

Voice

• Speech-to-text via OpenAI Whisper for transcribing voice messages received on any channel.
• Text-to-speech via OpenAI (voices: alloy, echo, fable, onyx, nova, shimmer) or ElevenLabs for generating spoken responses.

Dashboard

• Built-in web UI served as zero-dependency inline HTML on the configured port. No build step, no npm dependencies, no CDN calls.
• Includes real-time chat, analytics (token usage, tool calls, response times), memory browser with search, skill manager (install, enable, disable, delete), settings editor, and full data export/import.

Budget & Cost Controls

• Spending limits — set daily or monthly budgets per provider or globally. Zubo pauses requests when limits are reached, preventing surprise bills.
• Per-model cost tracking — view token usage and costs broken down by model in the dashboard. Full transparency into where your money goes.

Security

• API key authentication with Bearer tokens for all HTTP endpoints.
• Tool permission levels (safe, sensitive, dangerous) with confirmation tokens for destructive operations.
• Rate limiting per IP with configurable thresholds for chat and upload endpoints.
• File access restrictions preventing traversal outside the workspace directory.
• Shell command filtering blocking known-dangerous commands and patterns.
• Private IP blocking preventing SSRF attacks by blocking requests to internal network addresses.

Installation

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

Step 1: Install Zubo

Install Zubo globally using Bun (recommended) or npm:

# Using Bun (recommended)
bun add -g zubo

# Or using npm
npm i -g zubo

This places the zubo binary on your PATH, making it available from any terminal session.

Step 2: Run the Setup Wizard

zubo setup

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

• Create the ~/.zubo directory and all required subdirectories.
• Prompt you to select a primary LLM provider and enter your API key.
• Optionally configure one or more chat channels (Telegram, Discord, etc.).
• Generate the ~/.zubo/config.json file with your choices.
• Download the all-MiniLM-L6-v2 embedding model (~80 MB) for local semantic memory.
• Create a default SYSTEM.md system prompt that you can customize later.

Step 3: Start 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

Best Practices

• Start with zubo setup — let the interactive wizard configure everything. It handles directory creation, model downloading, and initial config generation so you do not have to do it manually.
• Write a custom system prompt in ~/.zubo/workspace/SYSTEM.md to give your agent a distinct personality and context about you, your work, your preferences, and your tools. The more specific you are, the better Zubo serves you.
• Use the dashboard for day-to-day management (chatting, browsing memory, managing skills) and the CLI for automation (scripting, cron, CI/CD pipelines).
• Enable API authentication if you are exposing the web port beyond localhost: zubo config set auth.enabled true, then create an API key via the dashboard or zubo auth create.
• Set rate limits for production to prevent abuse: zubo config set rateLimit.chatPerMinute 30.
• Use zubo start --daemon for always-on operation. Zubo writes a PID file and rotates logs automatically.
• Check zubo status and zubo logs for troubleshooting. The status command shows uptime, memory usage, connected channels, and pending scheduled jobs.
• Back up your data with zubo export for a full JSON export, or rely on the automatic daily SQLite backups in ~/.zubo/workspace/backups/.
• Enable smart routing to automatically send simple queries to fast, cheap models. Set smartRouting.enabled to true and configure a fastProvider (e.g., Groq) alongside your primary. This can cut costs significantly.
• Set a budget to avoid surprise bills: zubo config set budget.dailyLimit 5. Cost tracking is always active in the dashboard under Analytics → Costs.
• Configure failover providers so your agent stays available even if your primary LLM provider has an outage. For example, set Anthropic as primary and Ollama as failover for fully offline operation when the cloud is down.
• Keep skills small and focused — one skill per task. This makes them easier to test, share, and debug.

Next Steps

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

• Configuration — deep dive into every configuration option: LLM providers, channels, voice, rate limiting, authentication, sandbox settings, and a complete annotated example.
• Agents & Workflows — learn how to create custom sub-agents with focused system prompts and restricted tools, and build multi-agent pipelines with dependency resolution and parallel execution.
• Memory System — understand how semantic memory works, how to ingest documents, search your knowledge base, and tune the hybrid search weights.
• Skills — write, install, and share single-file TypeScript skills. Learn the skill manifest format, the sandbox environment, and the community registry.
• Channel Setup — step-by-step guides for configuring each channel: creating bots, obtaining tokens, setting up webhooks, and configuring allow-lists.
• Integrations — connect Zubo to GitHub, Google Workspace, Notion, Linear, Jira, and more. OAuth flows, API key setup, and usage examples.
• Security & Auth — harden your Zubo instance: API key management, tool permission levels, confirmation tokens, rate limiting, file access restrictions, and network security.
• API Reference — complete HTTP API documentation for programmatic access: endpoints, request/response formats, authentication, and WebSocket streaming.
• CLI Commands — full reference for every zubo CLI command: start, stop, status, config, auth, export, import, logs, and more.