Midnight Development Network (Devnet)
The devnet is a local 3-service blockchain network for Midnight development. It runs via Docker Compose and is managed through the /midnight-tooling:devnet command, which uses bash and Docker Compose commands directly.
Terminology -- Read This First
Four distinct components make up the local development environment. Always be precise about which is being referenced.
| Term |
What It Is |
Port |
Container |
| Devnet |
The complete local 3-service network managed as a unit |
N/A (all three below) |
Managed via Docker Compose |
| Node |
The Midnight blockchain node (Substrate-based) |
9944 |
midnight-node |
| Indexer |
GraphQL API for querying chain state and subscribing to events |
8088 |
midnight-indexer |
| Proof server |
Generates zero-knowledge proofs for transactions |
6300 |
midnight-proof-server |
The devnet is not a single service. It is the coordinated set of all three services. Starting the devnet starts all three; stopping it stops all three.
Prerequisites
Docker Desktop must be installed and running before the devnet can start. The three services together require adequate system resources.
| Check |
Command |
Expected |
| Docker installed |
docker --version |
Version string |
| Docker daemon running |
docker info |
System info (no connection errors) |
| Docker Compose available |
docker compose version |
Version string |
| Adequate resources |
Docker Desktop settings |
4 GB+ RAM allocated to Docker |
If Docker is not installed, see references/docker-setup.md for platform-specific installation instructions.
Quick Command Reference
| Command |
Purpose |
/midnight-tooling:devnet generate |
Create a devnet.yml from template with latest stable versions |
/midnight-tooling:devnet update |
Update image versions in an existing devnet.yml |
/midnight-tooling:devnet start |
Start all 3 services (generates compose file on first run) |
/midnight-tooling:devnet stop |
Stop all containers |
/midnight-tooling:devnet restart |
Stop and restart the network |
/midnight-tooling:devnet status |
Check Docker container state for all services (fast) |
/midnight-tooling:devnet health |
Hit HTTP endpoints on each service to verify responsiveness (thorough, with timing) |
/midnight-tooling:devnet logs |
View recent logs from the network services |
/midnight-tooling:devnet config |
Show endpoint URLs, network ID, image versions, and file info |
Services
| Service |
Port |
Endpoint |
Purpose |
| Node |
9944 |
http://127.0.0.1:9944 |
Blockchain RPC (Substrate JSON-RPC) |
| Indexer |
8088 |
http://127.0.0.1:8088/api/v4/graphql |
GraphQL queries and subscriptions |
| Proof server |
6300 |
http://127.0.0.1:6300 |
Zero-knowledge proof generation |
The indexer also exposes a WebSocket endpoint at ws://127.0.0.1:8088/api/v4/graphql/ws for real-time subscriptions.
The network ID for local devnet is undeployed.
Scripts
The skill includes four helper scripts in ${CLAUDE_SKILL_DIR}/scripts/:
| Script |
Purpose |
Usage |
resolve-versions.sh |
Query Docker Hub for latest stable image versions |
Returns key=value pairs |
generate-devnet.sh |
Create devnet.yml from template with version substitution |
--template <path> --node-version X --indexer-version X --proof-server-version X [--directory <path>] |
check-staleness.sh |
Check age of a devnet.yml file |
Returns age_days=N and stale=true/false |
find-devnet.sh |
Locate a devnet.yml in standard locations |
[--file <path>] |
The compose file template is at ${CLAUDE_SKILL_DIR}/templates/devnet.yml.
Common Issues
| Symptom |
Cause |
Fix |
docker: command not found |
Docker not installed |
Install Docker Desktop — see references/docker-setup.md |
Cannot connect to the Docker daemon |
Docker Desktop not running |
Start Docker Desktop and wait for it to be ready |
docker compose: command not found |
Older Docker without Compose V2 |
Update Docker Desktop or install docker-compose-plugin |
| Services fail to start or exit immediately |
Insufficient Docker resources |
Allocate at least 4 GB RAM to Docker Desktop (see references/docker-setup.md) |
| Port 9944, 8088, or 6300 already in use |
Another process occupying a required port |
Stop the conflicting process; use lsof -i :<port> to identify it |
| Network starts but indexer not responding |
Indexer still syncing with node |
Wait 10-20 seconds after start; use /midnight-tooling:devnet health to check readiness |
| Stale chain state causing errors |
Corrupted or outdated volumes |
Restart with --remove-volumes for a clean slate |
| Container name conflicts |
Previous containers not cleaned up |
Stop the devnet first (/midnight-tooling:devnet stop), then start again |
Failed to fetch tags from Docker Hub |
Docker Hub unreachable or rate-limited |
Check internet connection; use --node-version etc. to specify versions manually |
| Architecture mismatch on Apple Silicon |
Image not available for arm64 |
See Apple Silicon note in references/docker-setup.md |
| Compose file stale warning |
File older than 5 days |
Run /midnight-tooling:devnet update to refresh image versions |
Wallet Operations
For wallet management, funding, balance checking, transfers, and dust registration, use the midnight-wallet plugin. The wallet plugin's MCP tools work with any running devnet — it auto-detects the services by Docker image name.
Status & Health Probes
For status and health checks from inside a script, the statusline, or a doctor agent, use the midnight-tooling:devnet-health skill. It provides two bash scripts (status.sh, health.sh) that report container state and per-service HTTP health using only bash, docker, and curl.
Reference Files
Consult these for detailed procedures:
| Reference |
Content |
When to Read |
references/network-lifecycle.md |
Generate, update, start, stop, restart flows; staleness checking; compose file locations; project naming; typical workflows |
Managing the devnet lifecycle |
references/docker-setup.md |
Docker installation per platform, daemon troubleshooting, resource configuration, port conflicts |
Docker installation issues or first-time setup |
references/compose-structure.md |
Anatomy of devnet.yml: every service, env var, healthcheck, dependency, and port explained; guidance on bespoke modifications |
Debugging compose file issues or making custom changes |
references/version-resolution.md |
Docker Hub API, stable version filtering, compatibility matrix checking, graceful degradation |
Version resolution problems or understanding the update process |
Source: devrelaicom/midnight-expert — distributed by TomeVault.
1---2name: midnight-toolingdevnet3description: This skill should be used when the user asks about the Midnight local development network, including "start the devnet", "stop the devnet", "restart the network", "local development network", "midnight node", "midnight indexer", "network status", "network health", "devnet config", "network endpoints", "port 9944", "port 8088", "port 6300", "Docker Compose", "devnet not starting", "local blockchain", "devnet logs", "network ID", "generate devnet", "devnet versions", "update devnet", "devnet stale", "proof server", "devnet volumes", "clean slate", "docker containers", "devnet compose file", "devnet endpoints Use when this capability is needed.4---56# Midnight Development Network (Devnet)78The devnet is a local 3-service blockchain network for Midnight development. It runs via Docker Compose and is managed through the `/midnight-tooling:devnet` command, which uses bash and Docker Compose commands directly.910## Terminology -- Read This First1112> **Four distinct components make up the local development environment. Always be precise about which is being referenced.**1314| Term | What It Is | Port | Container |15|------|-----------|------|-----------|16| **Devnet** | The complete local 3-service network managed as a unit | N/A (all three below) | Managed via Docker Compose |17| **Node** | The Midnight blockchain node (Substrate-based) | 9944 | `midnight-node` |18| **Indexer** | GraphQL API for querying chain state and subscribing to events | 8088 | `midnight-indexer` |19| **Proof server** | Generates zero-knowledge proofs for transactions | 6300 | `midnight-proof-server` |2021The devnet is **not** a single service. It is the coordinated set of all three services. Starting the devnet starts all three; stopping it stops all three.2223## Prerequisites2425Docker Desktop must be installed and running before the devnet can start. The three services together require adequate system resources.2627| Check | Command | Expected |28|-------|---------|----------|29| Docker installed | `docker --version` | Version string |30| Docker daemon running | `docker info` | System info (no connection errors) |31| Docker Compose available | `docker compose version` | Version string |32| Adequate resources | Docker Desktop settings | 4 GB+ RAM allocated to Docker |3334If Docker is not installed, see `references/docker-setup.md` for platform-specific installation instructions.3536## Quick Command Reference3738| Command | Purpose |39|---------|---------|40| `/midnight-tooling:devnet generate` | Create a `devnet.yml` from template with latest stable versions |41| `/midnight-tooling:devnet update` | Update image versions in an existing `devnet.yml` |42| `/midnight-tooling:devnet start` | Start all 3 services (generates compose file on first run) |43| `/midnight-tooling:devnet stop` | Stop all containers |44| `/midnight-tooling:devnet restart` | Stop and restart the network |45| `/midnight-tooling:devnet status` | Check Docker container state for all services (fast) |46| `/midnight-tooling:devnet health` | Hit HTTP endpoints on each service to verify responsiveness (thorough, with timing) |47| `/midnight-tooling:devnet logs` | View recent logs from the network services |48| `/midnight-tooling:devnet config` | Show endpoint URLs, network ID, image versions, and file info |4950## Services5152| Service | Port | Endpoint | Purpose |53|---------|------|----------|---------|54| **Node** | 9944 | `http://127.0.0.1:9944` | Blockchain RPC (Substrate JSON-RPC) |55| **Indexer** | 8088 | `http://127.0.0.1:8088/api/v4/graphql` | GraphQL queries and subscriptions |56| **Proof server** | 6300 | `http://127.0.0.1:6300` | Zero-knowledge proof generation |5758The indexer also exposes a WebSocket endpoint at `ws://127.0.0.1:8088/api/v4/graphql/ws` for real-time subscriptions.5960The network ID for local devnet is `undeployed`.6162## Scripts6364The skill includes four helper scripts in `${CLAUDE_SKILL_DIR}/scripts/`:6566| Script | Purpose | Usage |67|--------|---------|-------|68| `resolve-versions.sh` | Query Docker Hub for latest stable image versions | Returns `key=value` pairs |69| `generate-devnet.sh` | Create `devnet.yml` from template with version substitution | `--template <path> --node-version X --indexer-version X --proof-server-version X [--directory <path>]` |70| `check-staleness.sh` | Check age of a `devnet.yml` file | Returns `age_days=N` and `stale=true/false` |71| `find-devnet.sh` | Locate a `devnet.yml` in standard locations | `[--file <path>]` |7273The compose file template is at `${CLAUDE_SKILL_DIR}/templates/devnet.yml`.7475## Common Issues7677| Symptom | Cause | Fix |78|---------|-------|-----|79| `docker: command not found` | Docker not installed | Install Docker Desktop — see `references/docker-setup.md` |80| `Cannot connect to the Docker daemon` | Docker Desktop not running | Start Docker Desktop and wait for it to be ready |81| `docker compose: command not found` | Older Docker without Compose V2 | Update Docker Desktop or install docker-compose-plugin |82| Services fail to start or exit immediately | Insufficient Docker resources | Allocate at least 4 GB RAM to Docker Desktop (see `references/docker-setup.md`) |83| Port 9944, 8088, or 6300 already in use | Another process occupying a required port | Stop the conflicting process; use `lsof -i :<port>` to identify it |84| Network starts but indexer not responding | Indexer still syncing with node | Wait 10-20 seconds after start; use `/midnight-tooling:devnet health` to check readiness |85| Stale chain state causing errors | Corrupted or outdated volumes | Restart with `--remove-volumes` for a clean slate |86| Container name conflicts | Previous containers not cleaned up | Stop the devnet first (`/midnight-tooling:devnet stop`), then start again |87| `Failed to fetch tags` from Docker Hub | Docker Hub unreachable or rate-limited | Check internet connection; use `--node-version` etc. to specify versions manually |88| Architecture mismatch on Apple Silicon | Image not available for arm64 | See Apple Silicon note in `references/docker-setup.md` |89| Compose file stale warning | File older than 5 days | Run `/midnight-tooling:devnet update` to refresh image versions |9091## Wallet Operations9293For wallet management, funding, balance checking, transfers, and dust registration, use the `midnight-wallet` plugin. The wallet plugin's MCP tools work with any running devnet — it auto-detects the services by Docker image name.9495## Status & Health Probes9697For status and health checks from inside a script, the statusline, or a doctor agent, use the `midnight-tooling:devnet-health` skill. It provides two bash scripts (`status.sh`, `health.sh`) that report container state and per-service HTTP health using only `bash`, `docker`, and `curl`.9899## Reference Files100101Consult these for detailed procedures:102103| Reference | Content | When to Read |104|-----------|---------|-------------|105| **`references/network-lifecycle.md`** | Generate, update, start, stop, restart flows; staleness checking; compose file locations; project naming; typical workflows | Managing the devnet lifecycle |106| **`references/docker-setup.md`** | Docker installation per platform, daemon troubleshooting, resource configuration, port conflicts | Docker installation issues or first-time setup |107| **`references/compose-structure.md`** | Anatomy of `devnet.yml`: every service, env var, healthcheck, dependency, and port explained; guidance on bespoke modifications | Debugging compose file issues or making custom changes |108| **`references/version-resolution.md`** | Docker Hub API, stable version filtering, compatibility matrix checking, graceful degradation | Version resolution problems or understanding the update process |109110---111> Source: [devrelaicom/midnight-expert](https://github.com/devrelaicom/midnight-expert) — distributed by [TomeVault](https://tomevault.io).112<!-- tomevault:4.0:skill_md:2026-06-15 -->
tomevault-io