Dashboard

vole serve starts the control-plane dashboard — one web server that manages all of your OpenVole agents from a single place in the browser. This is the primary way to run and operate OpenVole.

vole serve

By default it listens on http://localhost:3000. Set VOLE_DASHBOARD_PORT to use a different port.

NOTE

The control-plane dashboard replaces the old "one dashboard per project" model. The legacy @openvole/paw-dashboard is deprecated in its favor — see Infrastructure Paws. The single-engine vole init / vole start / vole run commands have been removed — OpenVole now runs as a server, and every agent is an agent.

Agents

An agent is fully isolated — its own vole.config.json, paws, identity files, and data directory. Each running agent is its own engine subprocess, parented to the vole serve process (not detached, so stopping vole serve stops them too).

One vole serve process manages every agent under a single OpenVole root directory. Agents are recorded in an agents.json registry at the root. Agents granted orchestrator authority show an orchestrator badge on their card.

Root Resolution

When you run vole serve, the OpenVole root is resolved in this order:

1. VOLE_HOME — if set, this explicit override always wins.
2. The current directory, if it is already a root — it contains an agents.json registry file.
3. The current directory, if it is empty — ignoring incidental files (.DS_Store, .git, .gitignore). It then becomes a new root.
4. Otherwise it refuses to start with a clear error. If a legacy ~/.openvole with agents exists, it tells you how to reach it.

On startup it logs the resolved root (with (new) if freshly created) and the tokenized dashboard URL:

OpenVole root: /Users/me/agents  (new)
Manage your agents at http://localhost:3000/?token=3f9c2a…

IMPORTANT

The dashboard is gated by a session token, generated on first run and persisted at <root>/.openvole/dashboard-token (or set VOLE_DASHBOARD_TOKEN). Open the printed URL — the token is required to reach the dashboard. It binds all interfaces by default; set VOLE_DASHBOARD_HOST=127.0.0.1 for localhost-only, and never expose the port raw on a public network. See Security › Dashboard / Control Plane.

TIP

Pick a directory to be your OpenVole root and run vole serve there — for example mkdir ~/agents && cd ~/agents && vole serve. To always serve a fixed root regardless of where you are, set VOLE_HOME:

VOLE_HOME=~/agents vole serve

WARNING

The old behavior — an implicit global ~/.openvole regardless of the current directory — is gone. If your existing agents live at ~/.openvole, reach them with cd ~/.openvole && vole serve or VOLE_HOME=~/.openvole vole serve. The error message prints these for you.

The Dashboard

The header has a agent switcher to create, start, stop, switch between, and delete agents. Each agent has five tabs:

Tab	What it shows
Overview	Paws (with health), tools, skills, tasks, schedules, and a live event log.
Chat	Talk to the agent — multiple chat sessions per channel, rendered as markdown.
Apps	Embedded paw panels (see below). Always visible.
Config	Structured form editor for the entire vole.config.json (see below).
Identity	Edit SOUL.md, USER.md, AGENT.md, HEARTBEAT.md, and BRAIN.md.

Creating a Agent

Click New agent in the header to open the new-agent form. Enter a name, and on successful create an onboarding step suggests the essential paws, pre-checked:

• @openvole/paw-brain
• @openvole/paw-session
• @openvole/paw-memory
• @openvole/paw-compact
• @openvole/paw-shell

Whichever you keep selected are installed into the new agent. (You can install more from the Config tab afterwards.)

The CLI equivalent is vole agent create <name> — see CLI Commands.

Deleting a Agent

Deleting an agent from the dashboard permanently deletes its directory on disk — config, identity, installed paws, and data — after a destructive confirmation.

WARNING

Deletion from the dashboard is equivalent to vole agent remove <name> --purge. The CLI's vole agent remove <name> without --purge removes the agent from the registry but keeps its files on disk.

Config Tab

The Config tab is a fully structured form — no raw-JSON textareas. Edit every section of vole.config.json with typed fields:

• brain — dropdown of installed brain paws
• loop — iterations, compaction, tool horizon, context budget, cost tracking
• heartbeat — enabled, interval, run-on-start
• security — sandbox toggle and per-paw filesystem paths
• paw permissions — each paw shows the permissions its manifest requests (network, env, filesystem, child processes) next to what the agent's config actually grants, with toggles to allow or revoke; writes go through the sandbox-weakening guard
• docker sandbox — image, limits, network mode
• rate limits — LLM/tool/task throttles
• tool profiles — per-source allow/deny lists
• SUB-AGENTS — named sub-agent profiles for spawn_agent (role, instructions, allowTools, denyTools, maxIterations) — config key agents; not to be confused with the server's agents
• NET (VoleNet) — fully structured with an on/off toggle for enabled, plus peers, share (tools/memory/session), TLS, routing, and the various modes

See Configuration for what each field means.

Apps — Embedded Paw Panels

Any paw can contribute its own UI to the dashboard. The Apps tab is always visible and shows one entry per panel-contributing paw in a left vertical nav, each rendered as a sandboxed iframe. If an agent has no panel paws, an empty state explains how to add one.

Panels are brain-free — a panel's tool calls go straight to the paw over IPC, with no LLM — and there are no per-paw web servers and no extra ports; everything flows through the single control-plane server.

To add a panel to your own paw, see Build an Embedded App.

Reference example

@openvole/paw-markets is a US-stock tracking paw whose Markets panel embeds this way. Install it into an agent from the Config tab and start the agent — its panel appears under the Apps tab.

Tools over MCP

The control plane exposes each running agent's own tools over the Model Context Protocol at POST /mcp/<agent>, so an MCP client can drive an agent's tools directly:

• tools/list enumerates the agent's registered tools; tools/call runs one through the agent's normal tool path (the same execution the brain uses).
• It's a stateless, streamable-HTTP MCP server built on the official @modelcontextprotocol/sdk — no extra ports, no per-paw servers.
• Token-gated: requests must carry the dashboard session token in the x-vole-token header.

The main consumer is the Claude Code brain: with CLAUDE_CODE_EXPOSE_TOOLS=1, Claude Code calls OpenVole's own tools as mcp__openvole__<tool> through this endpoint. The engine injects VOLE_DASHBOARD_URL, VOLE_AGENT_ID, and the token into each agent, so it wires up automatically under vole serve.

VoleNet Tab

The VoleNet tab is for talking to the humans behind your connected peer nodes. It has two parts:

• Peer list — every connected peer node, refreshed live (about every 5 seconds) with an online dot so dead peers drop off and new ones appear as they connect.
• Per-peer chat — pick a peer and chat with the person operating that node. Replies are answered by a human, not the brain, so there is no LLM cost. Each conversation is persisted in its own volenet:<peerId> paw-session (with an in-memory fallback), so transcripts survive restarts.

This is the human-to-human messaging mode. Cross-node chat where the peer's brain replies automatically is a separate, brain-callable tool — the net_message tool — described under VoleNet.