Micro-agent core. The smallest possible thing that other useful things can be built on top of.

OpenVole is a microkernel AI agent framework. It provides the agent loop and the plugin contract — nothing else. Everything useful (reasoning, memory, tools, channels, integrations) is a Paw or a Skill built by the community.

A fresh OpenVole installation has zero tools, zero skills, zero opinions. This is by design.

mkdir my-agent && cd my-agent
npm init -y
npm install openvole
npx vole init
npx vole paw add @openvole/paw-brain
npx vole paw add @openvole/paw-memory
npx vole paw add @openvole/paw-dashboard

Edit vole.config.json:

{
  "brain": "@openvole/paw-brain",
  "paws": [
    {
      "name": "@openvole/paw-brain",
      "allow": {
        "network": ["*"],
        "env": ["BRAIN_PROVIDER", "BRAIN_API_KEY", "BRAIN_MODEL",
                "GEMINI_API_KEY", "GEMINI_MODEL",
                "ANTHROPIC_API_KEY", "ANTHROPIC_MODEL",
                "OPENAI_API_KEY", "OPENAI_MODEL",
                "OLLAMA_HOST", "OLLAMA_MODEL"]
      }
    },
    {
      "name": "@openvole/paw-memory",
      "allow": { "env": ["VOLE_MEMORY_DIR"] }
    },
    {
      "name": "@openvole/paw-dashboard",
      "allow": { "listen": [3001], "env": ["VOLE_DASHBOARD_PORT"] }
    }
  ],
  "skills": [],
  "loop": { "maxIterations": 25, "maxContextTokens": 128000 }
}

Create .env:

BRAIN_PROVIDER=gemini
GEMINI_API_KEY=your-api-key

Run:

npx vole start

Tip: For easier access, install globally with npm install -g openvole — then use vole directly instead of npx vole.

Or use a preset:

# Basic (Brain + Memory + Dashboard)
curl -fsSL https://raw.githubusercontent.com/openvole/openvole/main/presets/basic.sh | bash

# With Telegram
curl -fsSL https://raw.githubusercontent.com/openvole/openvole/main/presets/telegram.sh | bash

# Everything
curl -fsSL https://raw.githubusercontent.com/openvole/openvole/main/presets/full.sh | bash

                         vole start (CLI)
                     readline prompt (vole>)
                              |
                              v
┌─────────────────────────────────────────────────────────────┐
│                       VoleEngine                            │
│                                                             │
│   Tool Registry ──── Skill Registry ──── Paw Registry       │
│        |                   |                  |             │
│   ┌────────────────────────────────────────────────┐        │
│   │              Agent Loop (per task)             │        │
│   │                                                │        │
│   │   BOOTSTRAP → PERCEIVE → COMPACT → THINK       │        │
│   │       |          |          |         |         │        │
│   │   Load data  Enrich     Compress   Brain       │        │
│   │   + VoleNet  context    old msgs   plans       │        │
│   │                                                │        │
│   │   → ACT → OBSERVE → loop                       │        │
│   │      |        |                                │        │
│   │   Execute   Record                             │        │
│   │   tools     results                            │        │
│   │                                                │        │
│   │       Context Budget Manager                   │        │
│   └────────────────────────────────────────────────┘        │
│                                                             │
│   Task Queue ── Scheduler ── Message Bus ── Cost Tracker    │
│                                                             │
│   VoleNet (optional distributed networking)                 │
│   ├── WebSocket + Ed25519 Auth                              │
│   ├── Remote Tools + Load Balancing                         │
│   └── Memory/Session Sync + Leader Election                 │
│                                                             │
└──────┬──────────┬──────────┬──────────┬─────────────────────┘
       |          |          |          |
  [Brain Paw] [Channel]  [Tools]   [In-Process]
   paw-brain  Telegram   Browser    Compact
   (unified)  Slack      Shell      Memory
              Discord    Database   Session
                         MCP        Dashboard

Official Paws across four categories: Brain, Channel, Tool, and Infrastructure.

The only thing OpenVole does natively:

Bootstrap → Perceive → Compact → Think → Act → Observe → loop

Paws are tool providers. They connect OpenVole to the outside world — APIs, databases, browsers, messaging platforms. Each Paw runs in an isolated subprocess with capability-based permissions.

npx vole paw add @openvole/paw-telegram

Skills are behavioral recipes. A skill is a folder with a SKILL.md file — no code, no build step. Compatible with ClawHub (13,000+ skills).

npx vole clawhub install summarize

---
name: summarize
description: "Summarize text, articles, or documents"
---
When asked to summarize content:
1. Identify the key points
2. Condense into 3-5 bullet points
...

The Brain is a Paw — the core is LLM-ignorant. Use @openvole/paw-brain — a single unified brain paw that supports all providers:

• Anthropic Claude — BRAIN_PROVIDER=anthropic
• OpenAI — BRAIN_PROVIDER=openai
• Google Gemini — BRAIN_PROVIDER=gemini
• xAI Grok — BRAIN_PROVIDER=xai
• Ollama (local) — BRAIN_PROVIDER=ollama

Auto-detects provider from available API keys if BRAIN_PROVIDER is not set. Provider-specific env vars (e.g. GEMINI_API_KEY) take precedence over generic BRAIN_API_KEY.

Legacy single-provider paws (paw-ollama, paw-claude, paw-openai, paw-gemini, paw-xai) are deprecated but still available.

Periodic wake-up — the Brain checks HEARTBEAT.md and decides what to do. No user input needed. Uses cron expressions:

{ "heartbeat": { "enabled": true, "cron": "*/30 * * * *" } }

Brain-created schedules use cron expressions and are stored in .openvole/schedules.json, surviving restarts. The heartbeat is recreated from config on each startup (intervalMinutes is auto-converted to cron).

"0 13 * * *"     — daily at 1 PM UTC
"*/30 * * * *"   — every 30 minutes
"0 9 * * 1"      — every Monday at 9 AM

Persistent memory with daily logs scoped by task source:

.openvole/paws/paw-memory/
├── MEMORY.md       # Shared long-term facts
├── user/           # CLI session logs
├── paw/            # Telegram/Slack logs
└── heartbeat/      # Heartbeat logs

Conversation continuity across messages. Auto-expiring transcripts per session ID. Session data lives in .openvole/paws/paw-session/, organized by session ID (e.g., cli:default/, telegram:123/).

Bridge 1000+ community MCP servers into the tool registry via paw-mcp. MCP tools appear alongside Paw tools — the Brain doesn't know the difference.

• MCP tools are auto-discovered at runtime as MCP servers connect
• Late tool registration — tools appear after the engine starts, not at boot
• MCP config lives in .openvole/paws/paw-mcp/servers.json (not in the installed package)

Example .openvole/paws/paw-mcp/servers.json:

{
  "servers": [
    {
      "name": "resend",
      "command": "npx",
      "args": ["-y", "resend-mcp"],
      "env": { "RESEND_API_KEY": "$RESEND_API_KEY" }
    }
  ]
}

Any Paw can discover and register tools at runtime using the register_tools mechanism — not just MCP. Tools registered this way appear in the tool registry like any other tool. This is a generic capability of the engine, not an MCP-specific feature.

Each Paw has its own local config directory at .openvole/paws/<name>/. The installed npm package stays immutable — all user configuration lives in the local paw directory.

.openvole/paws/
├── paw-memory/     ← memory data (MEMORY.md, daily logs)
├── paw-session/    ← session transcripts
└── paw-mcp/        ← MCP config (servers.json)

Example: paw-mcp reads its servers.json from .openvole/paws/paw-mcp/, not from node_modules/.

Per-task LLM cost estimation with provider pricing tables. Tracks input/output tokens and estimates USD cost per call. Supports auto-detection of local Ollama (free) vs cloud models.

Configure in loop:

• costTracking: "auto" (default) | "enabled" | "disabled"
• costAlertThreshold: warn when a task exceeds $X (e.g. 0.50)

Tasks support priority levels (urgent, normal, low) and dependencies (dependsOn: [taskId]). Urgent tasks jump the queue. Dependent tasks wait until all prerequisites complete.

Spawn specialized sub-agents with named profiles, tool restrictions, and context passing:

{
  "agents": {
    "researcher": {
      "role": "Research Agent",
      "allowTools": ["web_fetch", "memory_search", "workspace_write"],
      "maxIterations": 15
    }
  }
}

Sub-agents support 2-level depth, wait_for_agents for parallel coordination, and agent:completed events for async notification.

When an embedding provider is available (Ollama, OpenAI, or Gemini), memory_search uses hybrid retrieval — combining BM25 keyword matching with vector semantic similarity via Reciprocal Rank Fusion. Falls back to keyword-only when no embeddings are configured. Vector index is disposable — markdown files remain the source of truth.

Optional container-level isolation for paw subprocesses (stronger than default Node.js --permission):

{
  "security": {
    "docker": {
      "enabled": true,
      "image": "node:20-slim",
      "memory": "512m",
      "network": "none"
    }
  }
}

Connect multiple OpenVole instances across machines. Remote tools, shared memory, brain sharing — all authenticated with Ed25519 signatures.

{
  "net": {
    "enabled": true,
    "instanceName": "coordinator",
    "role": "coordinator",
    "port": 9700,
    "peers": [
      { "url": "http://worker:9701", "trust": "full" }
    ],
    "share": { "tools": true, "memory": true }
  }
}

Key capabilities:

• Remote tool execution — tools on remote peers appear in the local registry, transparent to the Brain
• Peer-specific targeting — us-monitor/shell_exec vs eu-monitor/shell_exec when multiple peers share a tool
• Brain sharing — brainless workers delegate thinking to a coordinator (brainSource: "remote")
• Memory sync — write propagation and cross-peer search
• Session sync — shared conversations across devices
• Leader election — automatic failover, heartbeat coordination
• Load balancing — tasks route to the least-loaded peer
• 8 architecture patterns — from single-brain + workers to autonomous swarms

vole net init my-instance        # Generate Ed25519 identity
vole net show-key                # Share public key
vole net trust "vole-ed25519 ..." # Trust a peer
vole net status                  # Show network status

See VoleNet documentation for architecture patterns and setup guide.

OpenVole's own skill registry. Search, install, and publish skills via CLI:

vole skill search summarize          # Search VoleHub
vole skill install summarize         # Install with SHA-256 verification
vole skill publish ./my-skill        # Prepare for publishing

Prevent runaway costs with configurable limits on LLM calls, tool executions, and task enqueue rates.

Per-source tool filtering — restrict what Telegram users can trigger:

{ "toolProfiles": { "paw": { "deny": ["shell_exec", "fs_write"] } } }

Customize agent behavior with optional markdown files in .openvole/:

The Brain Paw loads these on startup and core builds the system prompt from them.

Agent scratch space at .openvole/workspace/ — for files, drafts, API docs, downloaded content. Path traversal protected. Tools: workspace_write, workspace_read, workspace_list, workspace_delete.

Encrypted key-value store at .openvole/vault.json:

• AES-256-GCM encryption when VOLE_VAULT_KEY is set
• Write-once semantics — prevents hallucination overwrites
• Metadata support — attach service, handle, URL context to entries
• vault_list never exposes values

Lightweight URL fetching via the web_fetch core tool — GET/POST with custom headers and body. No browser Paw needed for simple HTTP requests.

Core manages the full context pipeline via ContextBudgetManager:

• Token-aware budget — estimates tokens (4 chars/token text, 2 chars/token JSON), calculates budget breakdown per iteration
• Priority-based trimming — old tool results, old errors, old messages trimmed in order; never trims first user message or last 2 brain responses
• Compaction trigger — at 75% token usage, runs paw-compact to summarize old messages
• System prompt — built by core from BRAIN.md + identity files + skills + tools + memory (static-first ordering for provider prompt caching)
• Image handling — extracts base64 images from tool results and passes to Brain as provider-native image blocks
• Stuck loop detection — 3-tier escalation (warn at 5, dampen at 10, circuit breaker at 15 identical tool calls)

Configure via loop.maxContextTokens (default: 128000) and loop.responseReserve (default: 4000).

Real-time web UI — powered by paw-dashboard, another Paw you install like any other. Shows paws, tools, skills, tasks, schedules, and live events.

npx vole paw add @openvole/paw-dashboard

All paws live in PawHub and are installed via npm.

Install from npm:

npx vole paw add @openvole/paw-telegram
npx vole paw add @openvole/paw-browser

npx vole init                              # Initialize project
npx vole start                             # Start agent (interactive)
npx vole run "summarize my emails"         # Single task (headless — no dashboard/channels)

npx vole paw add @openvole/paw-telegram    # Install a Paw
npx vole paw list                          # List loaded Paws

npx vole skill create email-triage         # Create a local skill
npx vole skill search summarize            # Search VoleHub
npx vole skill install summarize           # Install from VoleHub
npx vole clawhub install summarize         # Install from ClawHub
npx vole clawhub search email              # Search ClawHub

npx vole tool list                         # List all tools
npx vole tool call list_schedules          # Call a tool directly (no Brain)

Enabled by default. Every subprocess Paw runs with Node.js permission model restrictions:

• Read access: Paw's own package directory, project root, .openvole/, node_modules/, OS temp directory, parent directories (for module resolution)
• Write access: .openvole/paws/<paw-name>/ (paw's own data directory), OS temp directory
• Network: Blocked by default — allowed when paw has network or listen permissions granted
• Child processes: Blocked by default — allowed only when user grants childProcess: true in config
• Additional paths: Grant via allow.filesystem in paw config or security.allowedPaths globally
• Opt-out: Set security.sandboxFilesystem: false to disable (not recommended)

{
  "security": {
    "sandboxFilesystem": true,
    "allowedPaths": ["/home/user/projects"]
  },
  "paws": [
    {
      "name": "@openvole/paw-shell",
      "allow": {
        "filesystem": ["./"],
        "env": ["VOLE_SHELL_ALLOWED_DIRS"],
        "childProcess": true
      }
    }
  ]
}

Paws that need child process access (paw-shell, paw-browser, paw-mcp) must have it explicitly granted — this prevents arbitrary code execution from untrusted paws.

Important: Non-Node child processes (shell commands, Chrome, etc.) are not restricted by the filesystem sandbox — Node's permission model only applies to Node processes. Granting childProcess: true effectively gives the paw unrestricted filesystem access through spawned commands. Only grant this to paws you trust.

If your Paw spawns external processes — child_process.exec(), spawn(), launching binaries (e.g. Puppeteer spawning Chrome), or starting server processes (e.g. MCP servers) — users will need to grant childProcess: true in their config for your Paw. Document this in your Paw's README so users know to add it. Paws that only make HTTP requests, read/write files, or communicate over IPC do not need it.

Every Paw declares what it needs in its manifest. The user grants permissions in config. Effective permissions are the intersection — a Paw can only access what it requested AND what the user approved.

Single vole.config.json — plain JSON, no imports:

{
  "brain": "@openvole/paw-brain",
  "paws": ["@openvole/paw-brain", "@openvole/paw-memory"],
  "skills": ["clawhub/summarize"],
  "loop": { "maxIterations": 25, "maxContextTokens": 128000 },
  "heartbeat": { "enabled": false, "cron": "*/30 * * * *" },
  "toolProfiles": { "paw": { "deny": ["shell_exec"] } }
}

OpenVole loads OpenClaw skills natively — same SKILL.md format, same metadata.openclaw.requires fields. Install directly from ClawHub:

npx vole clawhub install summarize

.openvole/
├── paws/
│   ├── paw-memory/          ← memory data
│   │   ├── MEMORY.md
│   │   └── user/, paw/, heartbeat/
│   ├── paw-session/         ← session transcripts
│   │   └── cli:default/, telegram:123/
│   ├── paw-brain/            ← brain paw data
│   │   └── BRAIN.md          ← system prompt (scaffolded on first run)
│   └── paw-mcp/             ← MCP config
│       └── servers.json
├── workspace/               ← agent scratch space
├── skills/                  ← local and clawhub skills
├── vault.json               ← encrypted key-value store
├── schedules.json           ← persistent cron schedules
├── SOUL.md                  ← agent personality
├── USER.md                  ← user profile
├── AGENT.md                 ← operating rules
└── HEARTBEAT.md             ← recurring job definitions

Both are open-source AI agent frameworks. Different philosophies, many shared concepts.

OpenVole is a newborn — a tiny vole just getting started. We share the same skill format, the same heartbeat pattern, and the same MCP ecosystem as OpenClaw. Skills written for one work on the other.

We're building something small, modular, and community-driven. If you like the microkernel approach — where every piece is a Paw you can swap, extend, or build yourself — come join us. Try it out, build a Paw, write a Skill, break things, and help this little vole grow.

See VOLECONTEXT.md for how OpenVole builds, enriches, and compresses context — including the lifecycle hooks (bootstrap, perceive, compact, think, act, observe) and how paws inject data into the Brain's prompt.

We welcome contributions! See CONTRIBUTING.md for guidelines.

For contributing Paws, see the PawHub CONTRIBUTING.md.

If it connects to something, it's a Paw. If it describes behavior, it's a Skill. If the agent calls it, it's a Tool. If it's none of these, it probably doesn't belong in OpenVole.

MIT