Architecture

Configuration Guide

🎮 Configuration Guide#

MindServer Settings (Port 55668)#

Agent Status Display#

Setting Type Description
gamemode string survival/creative/spectator
health int/int Current/Max HP
hunger int/int Current/Max hunger
x, y, z float 3D coordinates
biome string Current biome
inventory_slots int/int Used/Total slots
equipped string Held item
last_message string Most recent message

Agent Controls#

Action API Event Description
Send Message send-message Chat to specific agent
Stop Action TBD Cancel current action
Stay Still TBD Pause movement
Restart restart-agent Restart agent process
Disconnect stop-agent Disconnect from server
Remove destroy-agent Permanently remove

Connection Options#

Option Default Description
minecraft_version 1.21.1 Protocol version
host localhost Server hostname
port 25565 Server port
auth offline Auth type

Behavior Profile#

Option Default Description
base_profile survival Base behavior template
load_memory false Load memory on startup
init_message Hi! I'm ready... Initial prompt
only_chat_with [] Chat whitelist
language en Agent language

AI Settings#

Option Default Description
relevant_docs_count 5 RAG doc retrieval count
max_messages 15 Conversation history window
num_examples 2 Few-shot examples
max_commands -1 Max commands per response

Communication#

Option Default Description
narrate_behavior true Agent narrates actions
log_all_prompts true Log all AI prompts
show_command_syntax full Command syntax display
chat_ingame true Allow in-game chat
chat_bot_messages false Bot-to-bot messaging
speak false TTS narration

Vision & Rendering#

Option Default Description
allow_vision false Visual perception (experimental)
render_bot_view false Render bot’s POV

Security & Code#

Option Default Description
blocked_actions [] Blocked action types
allow_insecure_coding false Allow code execution
code_timeout_mins 10 Max code execution time

Dashboard Integration#

Data Flow# 

MindServer (55668)
    ↓ Socket.io events
Dashboard Server (55667 - dashboard.js)
    ↓ Relays events
Browser (socket-client.js)
    ↓ Updates DOM
User sees live data ✨

Key Socket.IO Events#

  1. agents-status — Agent online/offline state
  2. state-update — Full agent state (health/pos/inventory)
  3. bot-output — Agent messages/logs
  4. jsonl-log — Structured JSONL event stream

Dashboard UI Architecture#

  • Real-time Agent Cards: Health/hunger bars, position, inventory, equipped item, last message, quick actions
  • Agent Detail Panel: Stats, inline-editable config, message history, POV viewer embed
  • Configuration Dashboard: Bulk config changes, template profiles, sliders/toggles
  • Live Activity Feed: All chat, actions, errors, task completions — filterable by agent/type
  • Map Integration: Live agent positions, biome overlays, activity heatmaps

Implementation Roadmap#

Phase Features
1: Stabilize Fix duplicate processes, verify WebSocket, retry logic
2: Enhance Display Health/hunger bars, position, inventory preview
3: Add Controls Inline message input, quick action buttons, config editing
4: Advanced Map integration, task templates, bulk controls, analytics

Dashboard Relay Environment#

Variable Default Purpose
DASHBOARD_PORT / PORT 55667 HTTP + Socket.IO listen port
MINDSERVER_PORT 55668 MindServer upstream port
MINDSERVER_HOST localhost MindServer host
RCON_PASSWORD (empty) Enables RCON-backed routes
MOINCRAFT_HISTORY_STORE file file or redis for stats persistence
REDIS_URL — Required when history store = redis
DASHBOARD_API_TOKEN — Bearer token for mutating endpoints
DASHBOARD_ALLOWED_ORIGIN * Socket.IO CORS origins
DASHBOARD_TRUST_PROXY (unset) Set 1 for X-Forwarded-For behind reverse proxy
DASHBOARD_RATE_COMMAND_PER_MIN 30 Rate limit for command endpoints
MOINCRAFT_TAIL_SWARM_LOG (unset) Set 1 to tail swarm.log and emit JSONL
MOINCRAFT_SWARM_LOG_PATH logs/swarm.log Path to swarm log