Skip to content
Blink Labs

Quick Start Guide

Dingo

Section titled “Dingo”

A Cardano blockchain node written in Go which actively participates in network communications on the Cardano blockchain using the Ouroboros Network Node-to-Node family of mini-protocols.

⚠️ Dingo is a work in progress and is currently under heavy development


In this guide, we will walk you through downloading the Dingo binary and all the steps necessary to get the Dingo node running on the Cardano Preview network. To get started follow the steps below.


✅ This guide assumes a typical Linux setup. Please adjust commands and paths as needed.


Step 1 - Download Dingo Binary

Section titled “Step 1 - Download Dingo Binary”

Download the latest release from the Dingo releases page.

⚠️ Adjust the version and architecture to match your system.

mkdir -p ~/dingo
cd ~/dingo
wget https://github.com/blinklabs-io/dingo/releases/download/v0.83.1/dingo-v0.83.1-linux-amd64.tar.gz -O - | tar -xz

You can verify the binary works by running:

./dingo version

Alternative: Install with npm

Section titled “Alternative: Install with npm”

The @blinklabs/dingo package requires Node.js 22 or later and tar. It supports Linux, FreeBSD, and macOS on x64/amd64 or arm64. During installation, the package downloads the matching Dingo release and verifies its SHA-256 checksum.

Install it globally and verify the dingo command:

npm install --global @blinklabs/dingo
dingo --help

After a global installation, use dingo instead of ./dingo in the remaining quick-start commands. To check without a global installation, run:

npx @blinklabs/dingo --help

Run a Local Single-node Devnet

Section titled “Run a Local Single-node Devnet”

Run a local single-node devnet with the downloaded binary:

./dingo devnet

For a global npm installation, run dingo devnet. Without a global installation, use:

npx @blinklabs/dingo devnet

Without --data-dir, Dingo stores the configuration, test keys, and chain data in a private temporary directory and removes that directory when the process exits. Each run starts a new chain.

Set --data-dir to retain and resume a chain:

./dingo devnet --data-dir ./.dingo-devnet

Run the same command again to resume the chain. The --reset option requires --data-dir and recreates the Dingo-managed state while retaining unrelated files in the directory:

./dingo devnet --data-dir ./.dingo-devnet --reset

The first persistent run requires an empty directory. Dingo rejects another invocation that uses the same directory while the node is running. Use the bundled keys and network for local testing only. Never use them with real funds.

Dingo provides faucet.skey, faucet.vkey, and faucet.addr in the cardano/keys/ directory. The bundled faucet.addr (addr_test1vztc80na8320zymhjekl40yjsnxkcvhu58x59mc2fuwvgkc332vxv) receives 900,000 test ADA (900_000_000_000 lovelace) at genesis for local transactions.

  • For a temporary ./dingo devnet run, Dingo prints the temporary run directory. Its cardano/keys/ directory contains the faucet files until the process exits.
  • For ./dingo devnet --data-dir ./.dingo-devnet, Dingo stores the files in ./.dingo-devnet/cardano/keys/.
  • Dingo restricts the faucet files and their directory to owner-only access.

When a persistent devnet resumes without --reset, Dingo restores or refreshes only the faucet files and rewrites the local configuration. It preserves producer credentials, the existing genesis allocation, and chain data.


Step 2 - Create dingo.yaml Configuration File

Section titled “Step 2 - Create dingo.yaml Configuration File”

For all Dingo v0.83.1 settings, defaults, and environment or command-line overrides, see the configuration reference. Download the release-matched dingo.yaml.example to use as a starting point for your own settings.

Dingo ships with embedded Cardano network configurations (genesis files, config.json) for preview, preprod, and mainnet. You do not need to download them separately.

Create a dingo.yaml file in your dingo directory. The $HOME variable will automatically expand to your home directory path:

cat <<EOF > ~/dingo/dingo.yaml
# Shared database path for the local blob and metadata stores.
databasePath: "$HOME/dingo/.dingo"


# Storage
plugins:
  storage:
    blob:
      provider: "badger"
      config:
        # Optional Badger data directory. When unset, `databasePath` applies.
        # dataDir: "$HOME/dingo/.dingo/badger"
    metadata:
      provider: "sqlite"
      config:
        # Optional SQLite data directory. When unset, `databasePath` applies.
        # dataDir: "$HOME/dingo/.dingo/metadata.db"


  api:
    blockfrost:
      provider: "builtin"
      config:
        port: 0
    mesh:
      provider: "builtin"
      config:
        port: 0
    utxorpc:
      provider: "builtin"
      config:
        port: 0


# Mempool
# `plugins.mempool.config.capacity` is an optional override.
# Default: 1 MiB for Praos mode and normal serve mode, and 25 MiB for Musashi mode.
# Leave the key commented or omit it to use the mode default.
# plugins:
#   mempool:
#     config:
#       capacity: 1048576


# Mithril
mithril:
  aggregatorUrl: ""
  cleanupAfterLoad: true
  enabled: true
  verifyCertificates: true
  # Optional exact artifact identity for a fresh bootstrap only.
  # Mithril v1 uses a snapshot digest; Mithril v2 uses a Cardano database artifact hash.
  # pinnedDigest: ""


# Network
bindAddr: "0.0.0.0"
# Prometheus uses this independent address and defaults to loopback; it does
# not inherit bindAddr. Use --metrics-bind-addr or DINGO_METRICS_BIND_ADDR to
# override it. Set metricsPort to 0 to disable the metrics listener.
metricsBindAddr: "127.0.0.1"
metricsPort: 12798
healthPort: 12799
healthReadyGapSlots: 1000
debugPort: 0
network: "preview"
privateBindAddr: "127.0.0.1"
privatePort: 3002
relayPort: 3001
socketPath: "$HOME/dingo/dingo.socket"
# Total NtC connection limit. Dingo ignores non-positive values.
# CLI: --max-ntc-conns; environment: DINGO_MAX_NTC_CONNS
maxNtCConns: 100
# Per-IP NtC connection limit. Dingo ignores non-positive values.
# CLI: --max-ntc-connections-per-ip; environment: DINGO_MAX_NTC_CONNECTIONS_PER_IP
maxNtCConnectionsPerIP: 5


# Storage
barkBaseUrl: ""
barkPort: 0
storageMode: "core"


EOF

📝 Leave debugPort set to 0 unless profiling is required. debugPort controls an optional pprof listener, stays separate from metricsPort, and remains disabled at 0.

📝 healthPort uses --health-port or DINGO_HEALTH_PORT; set healthPort: 0 to disable the health listener. healthReadyGapSlots uses --health-ready-gap-slots or DINGO_HEALTH_READY_GAP_SLOTS.

📝 Bark now derives its near tip safety window from the current ledger state. Do not look for or set a manual barkSecurityWindow value in this configuration.

💡 API servers stay inactive outside storageMode: "api", and a port value of 0 disables that API.

midnight:
  # Enable the Midnight gRPC server independently of Midnight indexing.
  # Default: false.
  serverEnabled: false
  # Expose gRPC reflection. Requires serverEnabled. Default: false.
  reflectionEnabled: false
  # Permit plaintext listening on a non-loopback host. A configured TLS
  # certificate and key allow remote TLS exposure without this setting.
  # Default: false.
  allowInsecureRemote: false
  # Must be nonzero when serverEnabled is true. Default: 50051.
  port: 50051
  # Defaults to loopback; an empty value also uses 127.0.0.1.
  host: "127.0.0.1"
  authTokenPolicyId: ""
storageMode: "api"
plugins:
  api:
    blockfrost:
      provider: "builtin"
      config:
        port: 3000
    mesh:
      provider: "builtin"
      config:
        port: 8080
    utxorpc:
      provider: "builtin"
      config:
        port: 9090

💡 midnight.serverEnabled: false keeps the Midnight gRPC listener disabled; setting midnight.port alone does not expose it.

📝 midnight.authTokenPolicyId only applies in API storage mode with Midnight indexing. Leaving it empty keeps the broader default auth token matching behavior.

💡 Setting block-cache-size and index-cache-size to 0 with compression: false uses OS page cache (mmap) instead of BadgerDB’s internal caches. This dramatically reduces memory usage.


Step 3 - Open Network Ports

Section titled “Step 3 - Open Network Ports”

Configure UFW firewall rules to allow the ports required by Dingo.

💡 Tip: UFW stands for Uncomplicated Firewall and is used for managing iptables (netfilter) firewall rules.

To see which ports are currently open:

sudo ufw status numbered

Add Port 3001 for Ouroboros Node-to-Node (NtN) Communication

Section titled “Add Port 3001 for Ouroboros Node-to-Node (NtN) Communication”
sudo ufw allow 3001/tcp

Step 4 - Bootstrap from Mithril Snapshot

Section titled “Step 4 - Bootstrap from Mithril Snapshot”

Dingo has a built-in Mithril client that downloads and loads a snapshot automatically. This saves hours of sync time compared to replaying the chain from genesis.

Run the following command from your ~/dingo directory:

cd ~/dingo
./dingo mithril sync --config ~/dingo/dingo.yaml

📝 Check http://127.0.0.1:12799/health or http://127.0.0.1:12799/healthz for liveness and http://127.0.0.1:12799/readyz for readiness. The /health and /healthz checks use liveness checks, including event-loop responsiveness, rather than readiness-only checks. The /readyz check requires the configured tip-gap condition and database readiness. For block producers, it also requires a running forger with usable forging credentials, including remote KES readiness where applicable. It reports unready while the tip gap is unknown or outside healthReadyGapSlots. The container health check uses /health, not the metrics endpoint. The health listener remains available while dingo mithril sync runs.

📝 mithril.downloadMaxTransientRetries controls retries for transient bootstrap download failures such as TLS timeouts, HTTP 429 responses, and HTTP 5xx responses. The example uses the default value of 10.

Dingo will:

  1. Download the latest Mithril snapshot for your configured network
  2. Verify the certificate chain
  3. Load the snapshot into the database

This takes approximately 20-30 minutes depending on your system and network speed.

📝 If you skip this step, Dingo will sync from genesis when started, which takes significantly longer.


Step 5 - Start Dingo

Section titled “Step 5 - Start Dingo”

Once the Mithril snapshot has loaded, start the node:

cd ~/dingo
./dingo serve --config ~/dingo/dingo.yaml

You should see log output showing the node connecting to peers and syncing the remaining blocks to reach the chain tip.


Interested in running Dingo as a systemd service?

Section titled “Interested in running Dingo as a systemd service?”

Using a systemd service automatically starts Dingo when your system boots and restarts it if it exits unexpectedly. See our guide on how to create a startup service for Dingo.


Congratulations! Your Dingo node is now running.

Section titled “Congratulations! Your Dingo node is now running.”

Learn how to interact with Dingo using the Cardano CLI.

Doc Holiday logo

Docs authored by Doc Holiday

Edit page

Last updated: