Ecosystem

How Pandapi relates to the headless-bot world, and where the project is going. This page summarizes the roadmap; the full document is docs/ECOSYSTEM.md.

Status: everything on this page beyond the shipped v5.7.1 API is roadmap, not shipped.

The hard boundary

Pandapi launches the real Minecraft client. It does not speak the Minecraft protocol as a headless bot. It can launch and kill the game, read the console and semantic game.* events, and manage accounts, instances and content; it cannot inject in-game input or chat. Headless-bot frameworks (Mineflayer, SoulFire, Minecraft Console Client, ZenithProxy) speak the protocol directly and can act in-world.

The hub thesis

Pandapi is the orchestration, identity and observability hub; the bot frameworks are the in-world actors, executing via a companion process. Pandapi supplies what every actor needs and no framework provides well:

• Accounts and auth: the full Microsoft credential chain lives in the OS keyring; a planned local-only accounts.mint_bot_session hands frameworks short-lived, audited session material without them ever running their own login.
• Server lists: the instance server registry, joined to live status, as a shared catalog (stats.servers).
• Fleet orchestration: the existing ops registry and event ring extended to bots and fleets.
• Live stats: recurring server polling emitting onto the same seq'd, replayable event bus as game.*.
• An LLM/MCP control plane: one agent surface over launcher, bots and stats alike.

Four planes

1. Core (existing, Rust/gpui): owns identity (keyring), instances, content, the server registry, the event ring, ops, scopes and the path jail. Gains four thin new domains (bots.*, fleet.*, stats.*, companion.*), one identity command (accounts.mint_bot_session), and ~20 new event types. Nothing else changes.
2. Companion (pandapi-botd, Node/TS): the single forced out-of-process component, behind one BotAdapter contract. Hosts MIT bots (Mineflayer) in-process; drives copyleft frameworks (SoulFire gRPC, MCC WebSocket, ZenithProxy HTTP) as separate, unmodified child processes; runs the SLP/Query stats poller. Local-only, path-jailed.
3. MCP bridge (pandapi-mcp): a separate adapter turning api.describe into an MCP tool/resource surface; optionally aggregates a bot-framework MCP (the two-server topology).
4. Consumers: LLM/MCP agents and the web client. Both receive identity and targets from core and act through companions or the browser; neither sits in the trusted core.

The actors

Framework	Role	Integration
Mineflayer (Node, MIT)	The reference in-world actor: pathfinding, digging, inventory, chat	Hosted in-process in pandapi-botd
SoulFire	The fleet-scale actor, already API-first (gRPC)	Unmodified child process, loopback-bound
Minecraft Console Client (MCC)	Scriptable chat/command actor over WebSocket RPC	Child process; bots.exec gated
ZenithProxy	Persistent-presence actor (holding a 2b2t queue slot after the human logs off)	Child process via its HTTP API + local proxy
ekaii-web-client	GUI-less browser front door and visual bot console	Self-hosted proxy; the server registry as its multiplayer list; viewer attach
MCP / LLM agents	The agent surface over everything above	pandapi-mcp, generated from api.describe

Planned API surface (summary)

• bots.* (new bots scope): frameworks, spawn, despawn, list/get, command (a canonical verb vocabulary: move_to, look_at, dig, place, equip, chat, run_command, ...; unsupported verbs return a structured unsupported_verb error), chat, inventory, attach_viewer. bots.exec (raw code execution in a framework) is quarantined behind its own local-only, off-by-default scope.
• fleet.*: create (one parent op, member spawns as child ops), scale, stop, list/get, broadcast, assign; one-account-per-member enforced for online-mode targets.
• stats.*: poll, watch/unwatch (recurring, event-emitting), list, servers (registry joined to last-known status). servers.status stays local-only; the poller runs in botd.
• accounts.mint_bot_session (local-only, accounts scope): the identity linchpin. Core already runs the full MSA to Minecraft token chain; this exports short-lived, single-use, TTL-bounded, audited session material per framework format, access-token-preferred. The one category-changing capability, and the enabler for all online-mode in-world work.
• companion.* (local-only): registration, op progress updates, and authenticated telemetry ingest (bots.emit) so nothing on the network can poison the seq'd ring.
• ~20 new event types (server.status, bot.spawned/ready/disconnected/kicked/died/chat/health/error/moved, fleet.*, bots.auth_prompt, companion.*) riding the existing seq + 4096 replay ring + filters, unifying real-client game.* and bot/fleet telemetry on one bus.

Phased plan

Phase	Scope	Effort
0	Stats substrate: stats.* poller, server.status event, the shared server catalog; PANDAPI_* env aliases added alongside PANDAPI_API_* (which stay authoritative)	days
1	LLM control plane: pandapi-mcp generated from api.describe, event/log resources, scope inheritance	days
2	Offline bots + identity foundation: pandapi-botd with the Mineflayer adapter, bots.*, offline mint_bot_session; survives LibreLogin + Velocity on a staging server	~1 week
3	Premium identity bridge: per-framework session formats, device-code prompts (bots.auth_prompt), full hardening + audit; gated on proof that a Pandapi-minted session is accepted by a framework	~1 week
4	Fleets + SoulFire: fleet.*, gRPC adapter, staggered joins, per-bot egress; 20-40 bots on owned hardware	1-2 weeks
5	MCC / ZenithProxy / web-client / AFK fleets (owned servers only): highest abuse and ban exposure, so last	as demand dictates

Risks and constraints (from the full document)

• Licensing: the launcher is MIT (clean fork); copyleft risk lives entirely in the bot frameworks, which is why copyleft actors run as separate unmodified child processes of pandapi-botd.
• Accounts and ToS: bot use of premium accounts carries ban risk; minted sessions are single-use, TTL-bounded, audited, and fleets enforce one account per member; AFK runs are gated to authorized targets.
• Protocol drift: frameworks lag new Minecraft protocol versions; adapters declare supported version ranges.
• Runtime scale: the launcher's tokio runtime is multi_thread with a single worker and a sequential dispatch loop; any handler that awaits inline blocks the whole queue, so all new orchestration work is spawned, and fleet load stays in the companion.
• The document closes with 12 open blindspots ordered by thesis risk; the two flagged verify-first are the real protocol number for Minecraft 26.2 and the proof that frameworks accept Pandapi-minted premium sessions.

Related pages

• Automation-and-AI: what you can automate today, with the shipped API.
• Network-Mode-and-Security: the security model everything above inherits.
• Command-Reference: the shipped surface.