Ganglion — Operator's Manual
Ganglion is a domain-specific execution engine for Bittensor subnet mining. It provides a pipeline framework for orchestrating autonomous mining agents that search for optimal model configurations. It exposes a CLI, an HTTP bridge API, and a Python library. Ganglion is search infrastructure — it doesn't know what a good model looks like, it knows how to search for one.
Quick Reference
CODEBLOCK0
Mode Detection
Ganglion supports two modes. Always check which mode applies before running commands.
- - Local mode: No
GANGLION_URL set, or GANGLION_PROJECT is set. Use ganglion <command> <project_dir> directly. - Remote mode:
GANGLION_URL is set. Use curl against the HTTP bridge.
CODEBLOCK1
Response Format
All HTTP bridge endpoints (except health probes) return responses in a standard envelope:
- - Success:
{"data": <payload>} — use jq .data to extract - Error: INLINECODE7
Health probes (/healthz, /readyz) return raw JSON without the envelope.
Interactive API docs: $GANGLION_URL/v1/docs (Swagger UI).
Note: Unversioned routes (e.g. /status) still work but are deprecated. Always use /v1/.
How to Run
Prerequisites: Python >= 3.11, LLM_PROVIDER_API_KEY set (used by the LLM runtime).
Install: INLINECODE14
Scaffold a project:
ganglion init ./my-subnet --subnet sn9 --netuid 9
This creates
config.py,
tools/,
agents/, and
skill/ in the target directory.
Start in local mode:
CODEBLOCK3
Start in remote mode:
CODEBLOCK4
The project directory must contain a config.py that defines subnet_config (SubnetConfig) and pipeline (PipelineDef). See {baseDir}/references/configuration.md for full config details.
Key Features
Observe State
Query the current framework state — registered tools, agents, pipeline definition, knowledge, metrics, and run history. Local mode uses CLI commands; remote mode uses GET endpoints.
Full reference: INLINECODE23
Execute Pipelines
Run the full pipeline or a single stage. The orchestrator executes stages in dependency order, applies retry policies, injects accumulated knowledge into agent prompts, and records outcomes.
CODEBLOCK5
Mutate at Runtime (Remote Only)
Register new tools, agents, and components; patch the pipeline; swap retry policies; update prompts. All mutations are validated, audited, and reversible.
CODEBLOCK6
Pipeline operations: add_stage, remove_stage, update_stage. See {baseDir}/references/commands.md for all mutation endpoints.
Knowledge Store
Cross-run strategic memory that compounds over time. Records patterns (what worked) and antipatterns (what failed), then automatically injects relevant history into agent prompts. Knowledge is queried by capability and filtered by bot_id for multi-bot setups.
CODEBLOCK7
Rollback
Undo any mutation. Every mutation is recorded in an audit log with rollback data.
CODEBLOCK8
Multi-Bot Workflows
Multiple OpenClaw sessions share a knowledge pool via
--bot-id. Each bot's discoveries flow into the shared pool. Cooperation emerges from shared knowledge, not explicit coordination.
CODEBLOCK9
MCP Integration
Ganglion is a bidirectional MCP system: it can
consume external MCP servers (client mode) and
expose its own tools as an MCP server (server mode).
MCP Client Mode — Consuming External Tools
Connect to external MCP servers to add tools to the agent's repertoire. Tools from MCP servers appear as regular Ganglion tools with a configurable prefix.
CODEBLOCK10
MCPClientConfig options: name, transport (stdio|sse), command (for stdio), url (for sse), env, tool_prefix, category, timeout (default 30s).
MCP Server Mode — Exposing Ganglion Tools
Run Ganglion as an MCP server so external agents (Claude Code, Claude Desktop, OpenClaw) can call Ganglion tools directly.
CODEBLOCK11
Claude Code integration: This repo includes .mcp.json which auto-configures Claude Code to connect to Ganglion's MCP server via stdio. Claude Code will see all Ganglion tools natively in its tool palette.
Exposed MCP Tools (31 total)
Observation (11) — read-only state queries:
ganglion_get_status, ganglion_get_pipeline, ganglion_get_tools, ganglion_get_agents, ganglion_get_runs, ganglion_get_metrics, ganglion_get_leaderboard, ganglion_get_knowledge, ganglion_get_source, ganglion_get_components, INLINECODE48
Mutation (6) — write operations:
ganglion_write_tool, ganglion_write_agent, ganglion_write_component, ganglion_write_prompt, ganglion_patch_pipeline, INLINECODE54
Execution (3) — run operations:
ganglion_run_pipeline, ganglion_run_stage, INLINECODE57
Admin (5) — rollback and MCP management:
ganglion_rollback_last, ganglion_rollback_to, ganglion_connect_mcp, ganglion_disconnect_mcp, INLINECODE62
Compute (6) — infrastructure tools:
compute_status, compute_jobs, compute_job_detail, compute_routes, write_dockerfile, INLINECODE68
Multi-Role MCP Serving
Run one process with multiple MCP server instances, each with different access levels and auth tokens.
CODEBLOCK12
Roles filter tools by category. null categories = access to all tools. Each role gets a separate port and bearer token for SSE transport. At most one role can use stdio transport.
Per-Bot Usage Tracking
When running with
--roles, a shared
UsageTracker records per-bot tool calls (tool name, success/failure, timestamp, duration) to
.ganglion/usage.db. Query via
/usage endpoint on any SSE role.
Connecting Other Agents to Ganglion's MCP Server
OpenClaw and other LLM agents can start Ganglion's MCP server for themselves or for other agents to connect to. Use SSE transport for generic MCP clients that don't support stdio.
CODEBLOCK13
For OpenClaw: OpenClaw reads skills and invokes commands via bash/curl — it doesn't connect to MCP natively. To give OpenClaw access to Ganglion tools, use the CLI (local mode) or HTTP bridge (remote mode) documented above. OpenClaw can also start an MCP server so that other MCP-capable agents (Claude Desktop, Cursor, etc.) can connect:
CODEBLOCK14
For generic MCP clients (Cursor, Windsurf, custom): Point your client's MCP config at the SSE endpoint:
- - Server URL: INLINECODE74
- Messages endpoint: INLINECODE75
- Transport: SSE
- Auth: Bearer token (if using roles)
Common Workflows
See {baseDir}/examples/common-workflows.md for full step-by-step guides.
- 1. First run:
ganglion init → edit config.py → INLINECODE79 - Iterative mining: check status → review knowledge → run pipeline → check metrics → repeat
- Dynamic mutation: observe tools/agents → register new tool via API → patch pipeline → run
- Multi-bot setup: start multiple servers with different
--bot-id values on the same project - MCP integration: connect external tool servers → tools appear in registry → agents can use them
When Things Go Wrong
| Symptom | Likely Cause | Fix |
|---|
| INLINECODE81 | Wrong project path | Verify path contains INLINECODE82 |
| INLINECODE83 errors |
Missing or invalid API key |
export LLM_PROVIDER_API_KEY=sk-... |
|
ConcurrentMutationError | Mutating during a pipeline run | Wait for the run to finish |
|
PipelineValidationError | Invalid pipeline DAG (cycles, missing deps) | Check
ganglion pipeline output |
| Agent stuck / max turns reached | Agent cannot make progress | Review knowledge, swap retry policy, adjust prompts |
Full troubleshooting: INLINECODE88
Retry Policies
Four built-in policies control how stages retry on failure:
- - NoRetry — single attempt
- FixedRetry — retry N times (default: 3)
- EscalatingRetry — increase temperature per attempt, optional stall detection
- ModelEscalationRetry — climb a model cost ladder (cheap → expensive)
Three presets: SN50_PRESET (escalating + stall detection), SIMPLE_PRESET (fixed), AGGRESSIVE_PRESET (model escalation).
Additional Resources
- - Full CLI & API reference: INLINECODE92
- Configuration guide: INLINECODE93
- Operational procedures: INLINECODE94
- Troubleshooting: INLINECODE95
- Workflow examples: INLINECODE96
- Sample API requests: INLINECODE97
- Health check script: INLINECODE98
Ganglion — 操作手册
Ganglion 是专为 Bittensor 子网挖矿设计的领域特定执行引擎。它提供了一套管道框架，用于编排搜索最优模型配置的自主挖矿代理。该引擎提供 CLI、HTTP 桥接 API 和 Python 库。Ganglion 是搜索基础设施——它不知道什么样的模型是好的，它只知道如何搜索。
快速参考
bash
搭建新项目
ganglion init ./my-subnet --subnet sn9 --netuid 9
检查状态（本地模式）
ganglion status ./my-subnet
ganglion tools ./my-subnet
ganglion agents ./my-subnet
ganglion knowledge ./my-subnet --capability training --max-entries 10
ganglion pipeline ./my-subnet
运行（本地模式）
ganglion run ./my-subnet
ganglion run ./my-subnet --stage plan
ganglion run ./my-subnet --overrides {target_metric:accuracy}
启动 HTTP 桥接（远程模式）
ganglion serve ./my-subnet --bot-id alpha --port 8899
检查状态（远程模式）
curl -s $GANGLION_URL/v1/status | jq .data
模式检测
Ganglion 支持两种模式。运行命令前务必检查当前适用的模式。
- - 本地模式：未设置 GANGLIONURL，或设置了 GANGLIONPROJECT。直接使用 ganglion dir>。
- 远程模式：已设置 GANGLIONURL。使用 curl 访问 HTTP 桥接。
bash
if [ -n $GANGLIONPROJECT ] || [ -z $GANGLIONURL ]; then
echo local
else
echo remote
fi
响应格式
所有 HTTP 桥接端点（健康检查除外）均以标准信封格式返回响应：
- - 成功：{data: } — 使用 jq .data 提取
- 错误：{detail: {error: {code: ERROR_CODE, message: ...}}}
健康检查端点（/healthz、/readyz）返回原始 JSON，不带信封。
交互式 API 文档：$GANGLION_URL/v1/docs（Swagger UI）。
注意： 无版本号的路由（如 /status）仍可工作但已弃用。请始终使用 /v1/。
如何运行
前置条件： Python >= 3.11，已设置 LLMPROVIDERAPI_KEY（由 LLM 运行时使用）。
安装： pip install ganglion
搭建项目：
bash
ganglion init ./my-subnet --subnet sn9 --netuid 9
这将在目标目录中创建 config.py、tools/、agents/ 和 skill/。
以本地模式启动：
bash
export GANGLION_PROJECT=./my-subnet
ganglion status $GANGLION_PROJECT
以远程模式启动：
bash
ganglion serve ./my-subnet --bot-id alpha --port 8899
export GANGLION_URL=http://127.0.0.1:8899
项目目录必须包含定义 subnet_config（SubnetConfig）和 pipeline（PipelineDef）的 config.py。完整配置详情请参见 {baseDir}/references/configuration.md。
主要功能
观察状态
查询当前框架状态——已注册的工具、代理、管道定义、知识、指标和运行历史。本地模式使用 CLI 命令；远程模式使用 GET 端点。
完整参考：{baseDir}/references/commands.md
执行管道
运行完整管道或单个阶段。编排器按依赖顺序执行阶段，应用重试策略，将累积的知识注入代理提示，并记录结果。
bash
本地
ganglion run ./my-subnet
ganglion run ./my-subnet --stage plan
远程
curl -s -X POST $GANGLION_URL/v1/run/pipeline -H Content-Type: application/json -d {} | jq .data
curl -s -X POST $GANGLION_URL/v1/run/stage/plan -H Content-Type: application/json -d {} | jq .data
运行时变更（仅远程模式）
注册新工具、代理和组件；修补管道；交换重试策略；更新提示。所有变更均经过验证、审计且可逆。
bash
注册工具
curl -s -X POST $GANGLION_URL/v1/tools -H Content-Type: application/json \
-d {name:my_tool,code:
,category:training} | jq .data
修补管道
curl -s -X PATCH $GANGLION_URL/v1/pipeline -H Content-Type: application/json \
-d {operations:[{op:addstage,stage:{name:validate,agent:Validator,dependson:[train]}}]} | jq .data
管道操作：addstage、removestage、update_stage。所有变更端点请参见 {baseDir}/references/commands.md。
知识存储
跨运行的战略性记忆，随时间累积。记录模式（有效的方法）和反模式（失败的方法），然后自动将相关历史注入代理提示。按能力查询知识，并通过 bot_id 过滤以支持多机器人设置。
bash
本地
ganglion knowledge ./my-subnet --bot-id alpha --capability training
远程
curl -s $GANGLIONURL/v1/knowledge?capability=training&maxentries=10 | jq
回滚
撤销任何变更。每次变更都记录在审计日志中，并附带回滚数据。
bash
curl -s -X POST $GANGLION_URL/v1/rollback/last | jq
curl -s -X POST $GANGLION_URL/v1/rollback/0 | jq # 撤销所有变更
多机器人工作流
多个 OpenClaw 会话通过 --bot-id 共享知识池。每个机器人的发现流入共享池。协作源于共享知识，而非显式协调。
bash
两个本地会话
ganglion run ./my-subnet --bot-id alpha
ganglion run ./my-subnet --bot-id beta
两个远程服务器
ganglion serve ./my-subnet --bot-id alpha --port 8899
ganglion serve ./my-subnet --bot-id beta --port 8900
MCP 集成
Ganglion 是一个双向 MCP 系统：它可以消费外部 MCP 服务器（客户端模式），也可以暴露自己的工具作为 MCP 服务器（服务器模式）。
MCP 客户端模式——消费外部工具
连接到外部 MCP 服务器，为代理添加工具。来自 MCP 服务器的工具以可配置前缀的形式显示为常规 Ganglion 工具。
bash
静态：添加到 config.py
from ganglion.mcp.config import MCPClientConfig
mcpclients = [MCPClientConfig(name=weather, transport=stdio, command=[python, -m, weatherserver])]
动态：运行时通过 API 添加
curl -s -X POST $GANGLION_URL/v1/mcp/servers -H Content-Type: application/json \
-d {name:weather,transport:stdio,command:[python,-m,weather_server]} | jq .data
检查已连接的 MCP 服务器
curl -s $GANGLION_URL/v1/mcp | jq .data
断开 / 重新连接
curl -s -X DELETE $GANGLION_URL/v1/mcp/servers/weather | jq .data
curl -s -X POST $GANGLION_URL/v1/mcp/servers/weather/reconnect | jq .data
MCPClientConfig 选项：name、transport（stdio|sse）、command（用于 stdio）、url（用于 sse）、env、tool_prefix、category、timeout（默认 30s）。
MCP 服务器模式——暴露 Ganglion 工具
将 Ganglion 作为 MCP 服务器运行，使外部代理（Claude Code、Claude Desktop、OpenClaw）可以直接调用 Ganglion 工具。
bash
stdio 传输（Claude Desktop / Claude Code）
ganglion mcp-serve ./my-subnet --transport stdio
SSE 传输（基于 HTTP 的客户端）
ganglion mcp-serve ./my-subnet --transport sse --mcp-port 8900
带访问控制的多角色
ganglion mcp-serve ./my-subnet --roles ./
