Codebase Guide

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

# Scaffold a new project
ganglion init ./my-subnet --subnet sn9 --netuid 9
Check state (local mode)
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
Run (local mode)
ganglion run ./my-subnet
ganglion run ./my-subnet --stage plan
ganglion run ./my-subnet --overrides '{"target_metric":"accuracy"}'
Start HTTP bridge (remote mode)
ganglion serve ./my-subnet --bot-id alpha --port 8899
Check state (remote mode)
curl -s "$GANGLION_URL/v1/status" | jq .data

Mode Detection

Ganglion supports two modes. Always check which mode applies before running commands.

if [ -n "$GANGLION_PROJECT" ] || [ -z "$GANGLION_URL" ]; then
  echo "local"
else
  echo "remote"
fi

Response Format

All HTTP bridge endpoints (except health probes) return responses in a standard envelope:

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, OPENAI_API_KEY set (used by the LLM runtime).

Install: pip install ganglion

Scaffold a project:

ganglion init ./my-subnet --subnet sn9 --netuid 9

Start in local mode:

export GANGLION_PROJECT=./my-subnet
ganglion status $GANGLION_PROJECT

Start in remote mode:

ganglion serve ./my-subnet --bot-id alpha --port 8899
export GANGLION_URL=http://127.0.0.1:8899

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

Full reference: {baseDir}/references/commands.md

Execute Pipelines

# Local
ganglion run ./my-subnet
ganglion run ./my-subnet --stage plan
Remote
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

Mutate at Runtime (Remote Only)

# Register a tool
curl -s -X POST "$GANGLION_URL/v1/tools" -H "Content-Type: application/json" \
  -d '{"name":"my_tool","code":"","category":"training"}' | jq .data
Patch pipeline
curl -s -X PATCH "$GANGLION_URL/v1/pipeline" -H "Content-Type: application/json" \
  -d '{"operations":[{"op":"add_stage","stage":{"name":"validate","agent":"Validator","depends_on":["train"]}}]}' | jq .data

Pipeline operations: add_stage, remove_stage, update_stage. See {baseDir}/references/commands.md for all mutation endpoints.

Knowledge Store

# Local
ganglion knowledge ./my-subnet --bot-id alpha --capability training
Remote
curl -s "$GANGLION_URL/v1/knowledge?capability=training&max_entries=10" | jq

curl -s -X POST "$GANGLION_URL/v1/rollback/last" | jq
curl -s -X POST "$GANGLION_URL/v1/rollback/0" | jq    # undo ALL mutations

# Two local sessions
ganglion run ./my-subnet --bot-id alpha
ganglion run ./my-subnet --bot-id beta
Two remote servers
ganglion serve ./my-subnet --bot-id alpha --port 8899
ganglion serve ./my-subnet --bot-id beta  --port 8900

# Static: add to config.py
from ganglion.mcp.config import MCPClientConfig
mcp_clients = [MCPClientConfig(name="weather", transport="stdio", command=["python", "-m", "weather_server"])]
Dynamic: add at runtime via 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
Check connected MCP servers
curl -s "$GANGLION_URL/v1/mcp" | jq .data
Disconnect
curl -s -X DELETE "$GANGLION_URL/v1/mcp/servers/weather" | jq .data
Expose Ganglion tools as MCP server (for Claude Desktop etc.)
ganglion mcp-serve ./my-subnet --transport stdio