Prerequisites

REQUIRED

• ✓Node.js 18+ — runtime for the KyberBot CLI
• ✓Docker — required for memory services
• ✓Claude Code subscription — KyberBot runs on top of Claude Code

OPTIONAL

• ○Telegram account — if you want to message your agent via Telegram
• ○WhatsApp — if you want to message your agent via WhatsApp

node --version    # Node 20 or 22 LTS recommended (must be <25)
docker --version  # Should show Docker version
claude --version  # Should show Claude Code version
pnpm --version    # pnpm 9+ required (install: npm i -g pnpm)

Installation

# Install KyberBot (one time)
git clone https://github.com/KybernesisAI/kyberbot.git
cd kyberbot
pnpm install && pnpm run build
cd packages/cli && pnpm link --global && cd ../..

# Create your agent
mkdir ~/my-agent && cd ~/my-agent
kyberbot onboard

Think of the kyberbot/ folder like installing an app — you don't work inside it. The agent folder is your agent. Everything it knows, everything it learns, its entire personality and memory — all lives there.

The kyberbot onboard wizard walks you through 7 steps:

Starting Services

# Start all services (leave running)
kyberbot

# In a new terminal — talk to your agent
cd ~/my-agent && claude

This starts memory services (Docker), the REST API server, heartbeat scheduler, sleep agent, and any configured messaging channels. You'll see a splash screen with your agent's name and service status.

kyberbot                   # Start all services
kyberbot --no-sleep        # Disable sleep agent
kyberbot --no-channels     # Disable messaging channels
kyberbot --no-heartbeat    # Disable heartbeat scheduler

First Conversation

When you first open Claude Code in your agent folder, the agent will warmly introduce itself and ask to learn about you. This is normal — it is reading its SOUL.md and USER.md for the first time and wants to fill in the gaps. Share as much or as little as you like — everything gets stored in its brain for future sessions.

> Hey Atlas, what do you know about me?
> Remember that my product launch deadline is June 15th.
> What's on my schedule today?
> Create a skill for tracking my running mileage.

Updating

When a new version is released, the update command handles both the CLI source update and template refresh inside your agent instance:

cd ~/my-agent
kyberbot update              # Full update: CLI source + agent templates
kyberbot update --check      # Preview what would change
kyberbot update --templates  # Only refresh template files

The Core Idea

Most personal AI agent projects follow the same pattern: build a custom framework, wrap an LLM API, manage tokens, handle tool calling, implement memory from scratch, and deploy a server. The result is a complex system that costs money per token and requires ongoing maintenance.

KyberBot takes a different approach: build on top of Claude Code instead of building from scratch. Claude Code is already an exceptional AI agent. It just lacks persistence — memory, identity, scheduling, and communication channels. KyberBot adds exactly those things. Nothing more.

Philosophy

KyberBot is built on three beliefs:

The Claude Code Advantage

By building on Claude Code, KyberBot inherits capabilities that would take months to build from scratch:

Subscription Model

KyberBot costs nothing beyond your Claude Code subscription:

Who Is KyberBot For?

The brain is KyberBot's long-term memory system. It stores conversations, tracks entities and relationships, extracts structured facts with source confidence, detects contradictions, generates insights through reasoning, and continuously improves quality through background maintenance. All data lives locally — nothing leaves your machine unless you opt into Kybernesis Cloud.

Hybrid Search

Searches use Reciprocal Rank Fusion (RRF) to merge semantic, keyword, and temporal results without tuned weights. For entity queries, a 5-layer fact-first retrieval expands through the entity graph.

Sleep Agent Pipeline

The sleep agent runs continuously in the background, performing a 10-step maintenance cycle every hour:

KyberBot agents are not static. They evolve over days, weeks, and months through four mechanisms:

Evolution Over Time

What Is Protected

Not everything can be modified by the agent. These files are protected and require manual editing:

Safeguards

Every change the agent makes is trackable via git. Major changes are confirmed before writing. The agent tells you when it updates a living document. Evening reviews summarize what was learned and changed, giving you regular checkpoints to correct course.

git log --oneline SOUL.md    # See how personality evolved
git log --oneline USER.md    # See knowledge accumulation
git diff HEAD~10 SOUL.md     # Compare current vs 10 commits ago
git checkout HEAD~5 SOUL.md  # Revert to an earlier version

Summary

Three markdown files define your agent's identity, knowledge, and routine. The agent reads them at session start and updates them as it learns.

Document Interaction

The three documents work together: SOUL.md tells the agent how to communicate, USER.md tells it what it knows about you, and HEARTBEAT.md tells it what to do on a schedule. When running a heartbeat task, the agent reads all three for context. During conversation, it reads SOUL.md and USER.md and may update them with new information.

Skills are reusable capabilities — markdown files with structured metadata that teach the agent how to perform specific tasks your way, every time.

SKILL.md Format

---
name: running-tracker
description: Track and analyze running mileage
version: 1.0.0
requires_env: []
has_setup: false
---

# Running Tracker

## What This Does
Track daily runs and calculate weekly/monthly totals.

## How to Use
- "log a run"
- "running mileage"
- "how far did I run"

## Implementation
1. Extract: distance, duration, date, notes
2. Store in brain with tag "running"
3. Calculate weekly/monthly totals when queried
4. Compare against goals in USER.md

Auto-Generation

The most powerful way to create skills is to let the agent do it. The skill generator follows a consistent process:

Lifecycle Commands

kyberbot skill list           # List all installed skills
kyberbot skill info <name>    # Show details
kyberbot skill create <name>  # Scaffold a new skill
kyberbot skill remove <name>  # Remove a skill
kyberbot skill setup <name>   # Run skill setup
kyberbot skill rebuild        # Rebuild CLAUDE.md with current skills

Send a message on Telegram or WhatsApp and get a response from your agent with full personality, memory, and skill context. Both channels are optional.

kyberbot channel add telegram

kyberbot channel list                     # List configured channels
kyberbot channel add telegram              # Add Telegram
kyberbot channel add whatsapp              # Add WhatsApp
kyberbot channel add telegram --reverify   # Re-pair Telegram
kyberbot channel remove telegram           # Remove a channel
kyberbot channel status                    # Check status

KyberBot Desktop is an Electron app that wraps the CLI in a full GUI. One-click install, no terminal required — everything you can do from the command line, you can do from the app.

Installation

Download the DMG for macOS, or build from source:

git clone https://github.com/KybernesisAI/kyberbot.git
cd kyberbot
pnpm install

pnpm run dev          # Development with hot reload
pnpm run build        # Production build
pnpm run package:mac  # Creates DMG

Onboarding Wizard

First launch opens a 10-step onboarding wizard that walks you through agent creation, personality setup, Claude Code configuration, brain initialization, cloud sync, and channel setup — the same steps as kyberbot onboard but with a visual interface.

Run multiple KyberBot agents simultaneously, each with their own identity, memory, skills, and channels. A global registry tracks all agents and auto-assigns ports so they never collide. In fleet mode, agents are aware of each other and can proactively reach out during chat and heartbeat sessions — no user intervention required (see Agent Bus). Agents can also run on remote machines (VPS, other computers) and be managed alongside local agents — see Remote Agents for details.

Three Modes of Operation

Fleet CLI Commands

kyberbot fleet list                    # Show registered agents
kyberbot fleet register [path]         # Register an agent at path
kyberbot fleet unregister <name>       # Remove from registry
kyberbot fleet start                   # Start all agents in shared runtime
kyberbot fleet start --only atlas,nova # Start specific agents
kyberbot fleet stop [name]             # Stop agents
kyberbot fleet status                  # Health dashboard
kyberbot fleet defaults --auto-start a,b  # Set default agents

The Agent Bus is an inter-agent communication system. Agents can send messages to each other and receive Claude-powered responses — enabling delegation, knowledge sharing, incident coordination, and second opinions across your agent fleet. With proactive communication, agents autonomously decide when to reach out to each other during conversations and heartbeat tasks.

Proactive Communication

Agents are not limited to user-initiated bus commands. Every agent in the fleet is automatically aware of every other agent — their names, roles, and specializations are injected into every system prompt (chat sessions, heartbeat tasks, and messaging channels). During any conversation or heartbeat task, an agent can autonomously decide to contact another agent via kyberbot bus send.

How It Works

The bus is an in-process EventEmitter-based message system. When agent A sends a message to agent B, the following happens:

Topic Subscriptions

Agents can subscribe to topics from specific agents or from the entire fleet. When a matching message is sent on the bus, subscribers get a notification queued for their next heartbeat cycle or chat session — no interruption to their current work.

subscriptions:
  - from: atlas
    topic: security
  - from: "*"
    topic: incident

kyberbot bus subscribe <from> <topic>    # Subscribe to messages on a topic
kyberbot bus unsubscribe <from> <topic>  # Remove a subscription
kyberbot bus subscriptions               # List active subscriptions

Message Types

Broadcast: Send a message to all agents at once by setting to: '*' or using the broadcast command.

Persistence

All bus messages are stored in SQLite at ~/.kyberbot/bus.db. Messages survive fleet restarts and are fully searchable by agent, topic, and date.

Safety

CLI Commands

kyberbot bus send <agent> "<message>"    # Send to specific agent
kyberbot bus broadcast "<message>"       # Broadcast to all agents
kyberbot bus history                     # Show recent messages
kyberbot bus history --agent nova        # Filter by agent
kyberbot bus subscribe <from> <topic>    # Subscribe to messages on a topic
kyberbot bus unsubscribe <from> <topic>  # Remove a subscription
kyberbot bus subscriptions               # List active subscriptions

API Endpoints

When running in fleet mode, the fleet server exposes bus endpoints:

Three Modes

File Structure

my-agent/
├── SOUL.md              # Agent personality (living)
├── USER.md              # User knowledge (living)
├── HEARTBEAT.md         # Recurring tasks (living)
├── identity.yaml        # Agent identity config
├── .env                 # Secrets and configuration
├── heartbeat-state.json # Scheduler state
│
├── brain/               # Markdown knowledge files
│   ├── projects/
│   └── people/
│
├── skills/              # Skill files
│   └── my-skill/
│       └── SKILL.md
│
├── data/                # Runtime data (gitignored)
│   ├── chromadb/        # Vector storage
│   ├── entity-graph.db  # Entity graph
│   ├── timeline.db      # Timeline
│   └── sleep.db         # Sleep agent state
│
├── .claude/             # Claude Code config
│   ├── CLAUDE.md        # Operating instructions
│   └── settings.local.json
│
└── logs/                # Application logs

Multi-Agent Runtime

When running in fleet mode, the architecture extends to support multiple agents in a single process. Each agent is wrapped in an AgentRuntime that manages its own server, databases, channels, and heartbeat scheduler. The FleetManager orchestrates all runtimes, exposes the fleet API, and provides a shared FleetSleepScheduler that runs sleep cycles round-robin across agents instead of each agent running its own independent sleep process.

Each agent maintains its own ChromaDB collection for vector isolation, ensuring that brain searches only return results from the queried agent's memory. The Agent Bus connects all runtimes via an in-process EventEmitter, enabling inter-agent messaging without network overhead. In fleet mode, each agent also listens on its own per-agent port so existing tunnel URLs and channel webhooks continue to work unchanged.

Kybernesis is an optional cloud service that provides a queryable workspace memory for your agent. KyberBot works fully offline without it — Kybernesis adds cross-device access and cloud-backed recall that complements your local brain.

Setup

KYBERNESIS_API_KEY=your_api_key_here

That's all. No agent_id, no workspace_id, no identity.yaml changes. Can also be configured during onboarding.

kyberbot kybernesis query "..."     # Search cloud workspace memory
kyberbot kybernesis list            # Browse all memories
kyberbot kybernesis status          # Check connection status
kyberbot kybernesis disconnect      # Switch to local-only memory

Disconnecting

To switch back to local-only memory:

kyberbot kybernesis disconnect

This removes the API key from .env. After disconnecting, restart the server and Claude. Your cloud memories are preserved — nothing is deleted. To reconnect later, add the key back to .env.

Privacy

Kybernesis sees only the queries you send to it. It does NOT see your .env, local brain, WhatsApp/Telegram sessions, or Claude Code credentials. Data is encrypted in transit and at rest. You can delete your workspace and all data at any time. Kybernesis does not use your data for model training.

Using Without Kybernesis

KyberBot is fully functional without Kybernesis. All memory, search, and agent features work locally. Kybernesis adds convenience (cloud-backed recall, cross-device access) but is not required for any core functionality. The entire brain is in your project directory under data/ and brain/ — back it up with any method you prefer.

Complete reference for all KyberBot CLI commands. 18 top-level commands, 55 subcommands.

Core

run: --no-channels, --no-sleep, --no-heartbeat, -v/--verbose  |  update: --check, --templates  |  status: --json

Memory

Brain

Sleep Agent

Heartbeat

Skills

Sub-Agents

Channels

Tunnel

Kybernesis Cloud

Fleet

start: --only <agents>  |  defaults: --auto-start <agents>  |  register-remote: --url <ngrok-url> --token <api-token>

Agent Bus

history: --agent <name>, --limit <n>  |  subscribe: from can be "*" for all agents

Orchestration

issues: --all (include done/cancelled)  |  activity: --agent <name>  |  See Orchestration docs for full details

Manage agents running on other machines (VPS, other computers) from your desktop app or CLI. Agents communicate across machines via the Agent Bus.

Set Up a Remote Agent

Install KyberBot on the remote machine and configure it to accept incoming connections via an ngrok tunnel.

Register from CLI

Use the fleet CLI to register the remote agent with its ngrok URL and API token.

kyberbot fleet register-remote nova --url https://xyz.ngrok.dev --token kb_xxx
kyberbot fleet list  # Shows both local and remote agents

Register from Desktop

How Communication Works

Limitations

• •Can't start/stop remote agents from the desktop (no process control)
• •Log streaming not available for remote agents
• •Configuration changes require direct access to the remote machine

Security

Orchestration lets you organize your fleet of agents into a company. A CEO agent drives strategy — setting goals, creating issues, assigning work, and managing the backlog — while worker agents execute tasks autonomously. Humans only intervene when agents escalate blockers to the inbox. The entire system is managed from the desktop app; no CLI required.

Setup

Orchestration is initialized through a setup wizard in the desktop app. Open the Orchestration tab and you'll see the setup screen where you configure your company.

You can also initialize from the CLI with kyberbot orch init.

Org Chart

The org chart visualizes your company hierarchy. The CEO sits at the top and worker agents are arranged below. Adding or removing an agent from orchestration is independent of the fleet registry — an agent can be in the fleet without participating in orchestration.

Goals & KPIs

Goals give the CEO strategic direction. They exist at three levels: company, team, and agent. Each goal can have measurable KPIs attached, and goals form a hierarchy through parent/child relationships so team-level goals roll up into company objectives.

Projects

Projects group related goals and issues under a named umbrella. Every goal and issue can optionally belong to a project. Projects have two states: active and archived. Archiving a project hides its issues from the default board view but preserves all history.

Issue Board (Kanban)

The issue board is a seven-column Kanban view. Issues are the atomic unit of work — the CEO creates them, assigns them to workers, and workers execute them autonomously. Every issue gets a sequential ID in the format KYB-N.

Drag-and-drop: Drag issue cards between columns to manually change status. Click any card to open a slide-over panel with full details, comments, and inline editing.

Priority levels: Issues have four priority levels — critical, high, medium, and low. Workers always pick up the highest-priority issue first. Critical issues interrupt current work.

CEO Heartbeat

The CEO agent runs a special orchestrator heartbeat on a configurable interval (default: 30 minutes). Each heartbeat is a full strategic planning cycle where the CEO reads all available state and takes action.

What the CEO reads: Company goals and KPIs, all active projects, full issue board state, org chart and worker assignments, pending inbox items, recent activity log, and agent workload metrics.

What the CEO does: Creates new issues based on goals, assigns them to appropriate workers, manages the backlog, reviews completed work, responds to escalations, @-mentions workers to trigger execution, and proposes new goals or adjusts KPI targets.

Rate limits: The CEO is capped at 5 new issues and 3 new goals per heartbeat to prevent runaway planning.

Worker Heartbeat

Worker agents process issues through a serial queue. Each heartbeat, the worker checks out the highest-priority issue assigned to it, executes the work via Claude, and reports results.

@-Mention Triggers

When any agent or human posts a comment containing @agentname, that agent's heartbeat is triggered immediately. This is how the CEO delegates work in real time and how humans can direct agents from the desktop app.

Human Inbox

The inbox is where agents escalate problems they cannot solve. When a worker hits a blocker — a missing credential, an ambiguous requirement, a permission they lack — it creates an inbox item instead of guessing. The desktop app shows a badge count on the Inbox tab.

Urgency levels: high, normal, and low. High urgency items indicate production-impacting blockers where multiple agents may be stalled.

Responding: From the inbox, you can dismiss (no action needed), resolve (unblocks the linked issue), or respond with a comment. Using @agentname in your response triggers that agent's heartbeat so it can act on your guidance immediately.

Activity Log

Every action in the orchestration system is recorded in a full audit trail: issue creation, status transitions, assignments, comments, goal changes, inbox escalations, and heartbeat runs. The Activity tab displays events in reverse chronological order, filterable by agent and event type.

Artifacts / Files

When agents produce output — code files, reports, configuration changes — these are automatically detected from the Claude session output and linked as artifacts. The Files tab aggregates all artifacts across all issues, filterable by agent. Click any artifact to view its contents inline.

Live Session Logs

Every heartbeat run produces a session log. The Dashboard shows recent runs with their start time, duration, agent, and outcome. Click a run to view its full stream-json output in real time (for active runs) or after completion. Logs use offset-based polling for efficient incremental updates.

Settings

CLI Reference

All orchestration features are accessible from the kyberbot orch command group. Changes from the CLI are immediately visible in the desktop app and vice versa.

kyberbot orch init                          # Run the setup wizard
kyberbot orch status                        # Company overview, workloads, issue counts
kyberbot orch org                           # Display the org chart
kyberbot orch goals                         # List goals with KPI progress
kyberbot orch goals create "<title>"        # Create a new goal
kyberbot orch issues                        # List open issues
kyberbot orch issues create "<title>"       # Create a new issue
kyberbot orch issues assign <id> <agent>    # Assign an issue
kyberbot orch issues transition <id> <status>  # Move an issue
kyberbot orch inbox                         # Show pending inbox items
kyberbot orch inbox resolve <id>            # Resolve an inbox item
kyberbot orch activity                      # Recent activity log

REST API

In fleet mode, the fleet server exposes orchestration endpoints under /fleet/orch/*. The desktop app communicates exclusively through these endpoints.