Skip to main content

Devnet Configuration

Customize your local devnet for different development scenarios.

CLI Configuration​

Basic Options​

# Specify port
npx cardano-devkit start --port 9090

# Fast blocks (100ms)
npx cardano-devkit start --block-time 100

# Enable WebSocket subscriptions
npx cardano-devkit start --websocket

# Combine options
npx cardano-devkit start --port 9090 --block-time 200 --websocket

Environment Variables​

export CARDANO_DEVKIT_PORT=10080
export CARDANO_DEVKIT_BLOCK_TIME=200
export CARDANO_DEVKIT_WEBSOCKET=true

npx cardano-devkit start

Programmatic Configuration​

DevnetManager Options​

import { createDevnetManager } from 'cardano-devkit';

const devnet = createDevnetManager({
  // Network port for API
  port: 10080,

  // Block production interval (milliseconds)
  // Minimum: 100ms, Default: 1000ms
  blockTimeMs: 200,

  // Slot length in seconds (for protocol)
  slotLength: 0.2,

  // Enable WebSocket subscriptions
  enableWebSocket: true,

  // Enable multi-node setup (for future rollback testing)
  enableMultiNode: false,
  nodeCount: 1,
});

DevKit Configuration​

import { createDevKit } from 'cardano-devkit';

const devKit = createDevKit({
  // Network to connect to
  network: 'LocalDevnet',

  // Provider configuration
  provider: {
    type: 'koios',
    baseUrl: 'http://localhost:10080/api/v1'
  },

  // Enable debug logging
  debug: true,

  // Local devnet specific options
  localDevnetConfig: {
    blockTimeMs: 200,
    slotLength: 0.2,
    enableWebSocket: true
  }
});

Docker Compose Configuration​

For advanced customization, modify devnet/docker-compose.yml:

services:
  cardano-node:
    image: ghcr.io/intersectmbo/cardano-node:10.4.1
    environment:
      - BLOCK_TIME_MS=200
      - SLOT_LENGTH=0.2
    volumes:
      - ./data:/data
    ports:
      - "10301:3001"

  indexer:
    build: ./scripts
    environment:
      - PORT=10080
      - NODE_URL=http://cardano-node:3001
      - BLOCK_TIME_MS=200
      - ENABLE_WEBSOCKET=true
      - DB_PATH=/data/indexer.db
    ports:
      - "10080:10080"
    depends_on:
      - cardano-node

  explorer:
    image: cardano-explorer:latest
    environment:
      - API_URL=http://indexer:10080
    ports:
      - "10173:80"
    depends_on:
      - indexer

Block Time Recommendations​

Use CaseBlock TimeNotes
Rapid prototyping100msFastest feedback, high CPU
Normal development200-500msGood balance
Integration testing1000msMore realistic timing
CI/CD pipelines500msFast but stable
Testnet simulation20000msMatches public testnet

Resource Usage​

Minimum Requirements​

  • CPU: 2 cores
  • RAM: 4GB
  • Disk: 1GB
  • CPU: 4+ cores
  • RAM: 8GB
  • Disk: 10GB SSD

Resource Scaling​

// Lower resource usage
const devnet = createDevnetManager({
  blockTimeMs: 1000,      // Slower blocks = less CPU
  enableWebSocket: false, // Disable if not needed
});

// Higher performance
const devnet = createDevnetManager({
  blockTimeMs: 100,       // Fastest blocks
  enableWebSocket: true,  // Real-time updates
});

Network Isolation​

The local devnet runs in Docker with isolated networking:

Host Machine
├── localhost:10080 → Indexer API
├── localhost:10173 → Block Explorer
└── localhost:10301 → Cardano Node (n2n)

Docker Network (cardano-devnet)
├── cardano-node:3001  (internal)
├── indexer:10080      (exposed)
└── explorer:80        (exposed)

Note: Ports use 10XXX range to avoid conflicts with Next.js (3000), Vite (5173), etc.

Troubleshooting​

Port Conflicts​

# Check what's using port 10080
lsof -i :10080

# Use a different port
npx cardano-devkit start --port 11080

Docker Issues​

# Check Docker status
docker ps

# View logs
docker-compose -f devnet/docker-compose.yml logs -f

# Full reset
npx cardano-devkit reset
docker-compose -f devnet/docker-compose.yml down -v

Memory Issues​

# Increase Docker memory limit
# Docker Desktop: Settings > Resources > Memory

# Or reduce block speed
npx cardano-devkit start --block-time 1000

Next Steps​