Quick Start Guide
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
This guide covers downloading the Dingo binary and every step needed to run a Dingo node on the Cardano Preview network.
✅ 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 ~/dingocd ~/dingo wget https://github.com/blinklabs-io/dingo/releases/download/v0.94.1/dingo-v0.94.1-linux-amd64.tar.gz -O - | tar -xzYou can verify the binary works by running:
./dingo versionAlternative: 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.
The installer accepts only HTTPS URLs for release assets on its host allowlist. It rejects URLs that contain credentials or use non-443 ports. It also rejects redirects and DNS results that resolve to private or special-use IP addresses.
Install it globally and verify the dingo command:
npm install --global @blinklabs/dingodingo --helpAfter a global installation, use dingo instead of ./dingo in the remaining quick-start commands. To check without a global installation, run:
npx @blinklabs/dingo --helpRun 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📝 Dingo-generated devnet configuration sets
bindAddrto127.0.0.1, so devnet APIs and listeners accept local connections by default. Change the generated configuration deliberately to enable remote access.
For a global npm installation, run dingo devnet. Without a global
installation, use:
npx @blinklabs/dingo devnetWithout --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-devnetRun 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 --resetThe 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.
Note: Dingo accepts a --data-dir under existing symlinked ancestors, but
rejects symlinked or non-directory components in the state path itself,
including a component that another process replaces during setup. An existing
persistent directory must contain Dingo’s recognized DevNet marker and version
before Dingo restricts its permissions to owner only. If Dingo cannot recognize
the directory, startup fails and Dingo leaves it unchanged; Dingo does not
adopt arbitrary existing data.
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 devnetrun, Dingo prints the temporary run directory. Itscardano/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.94.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 for preview, preprod, mainnet, DijkstraNet (dijkstra), and prime-mainnet. You do not need to download them separately. Set network: "dijkstra" to select DijkstraNet; its network magic is 6.
Set the network value as follows to select Prime Mainnet:
network: "prime-mainnet"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"
# Storageplugins: 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 standard/Praos operation. Dingo uses 25 MiB when# runMode is "leios" or the network is Musashi, including "serve" mode.# Uncomment and configure capacity to override the automatic default. An# explicit capacity remains authoritative.# plugins:# mempool:# config:# capacity: 1048576
# Mithrilmithril: 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: ""
# NetworkbindAddr: "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: 12798healthPort: 12799healthReadyGapSlots: 1000debugPort: 0network: "preview"privateBindAddr: "127.0.0.1"privatePort: 3002relayPort: 3001socketPath: "$HOME/dingo/dingo.socket"# Total NtC connection limit. Dingo ignores non-positive values.# CLI: --max-ntc-conns; environment: DINGO_MAX_NTC_CONNSmaxNtCConns: 100# Per-IP NtC connection limit. Dingo ignores non-positive values.# CLI: --max-ntc-connections-per-ip; environment: DINGO_MAX_NTC_CONNECTIONS_PER_IPmaxNtCConnectionsPerIP: 5
# StoragebarkBaseUrl: ""barkPort: 0storageMode: "core"
EOF📝 Leave
debugPortset to0unless profiling is required.debugPortcontrols an optional pprof listener, stays separate frommetricsPort, and remains disabled at0.
📝
healthPortuses--health-portorDINGO_HEALTH_PORT; sethealthPort: 0to disable the health listener.healthReadyGapSlotsuses--health-ready-gap-slotsorDINGO_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
barkSecurityWindowvalue in this configuration.
💡 API servers stay inactive outside
storageMode: "api", and a port value of0disables 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: "" authTokenAssetName: ""storageMode: "api"plugins: api: blockfrost: provider: "builtin" config: port: 3000 mesh: provider: "builtin" config: port: 8080 utxorpc: provider: "builtin" config: port: 9090 host: "127.0.0.1"📝 The built-in UTxO RPC listener stays on loopback (
127.0.0.1) by default, even when the rootbindAddruses a broader address. Setplugins.api.utxorpc.config.hostexplicitly to expose it on another interface for remote clients.
💡
midnight.serverEnabled: falsekeeps the Midnight gRPC listener disabled; settingmidnight.portalone does not expose it.
📝 Set
midnight.authTokenPolicyIdandmidnight.authTokenAssetNametogether or leave both unset. A partial pair causes configuration and startup validation to fail. A configured policy ID must be exactly 56 hexadecimal characters (28 decoded bytes). Matching uses the exact policy ID and asset name.
💡 Setting
plugins.storage.blob.config.blockCacheSizeandplugins.storage.blob.config.indexCacheSizeto 0 withplugins.storage.blob.config.compression: falseuses OS page cache (mmap) instead of BadgerDB’s internal caches. This dramatically reduces memory usage. On-disk Badger compression requires a positiveplugins.storage.blob.config.blockCacheSize; Dingo rejects the configuration when the value is 0.
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 numberedAdd 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/tcpStep 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/healthorhttp://127.0.0.1:12799/healthzfor liveness andhttp://127.0.0.1:12799/readyzfor readiness. The/healthand/healthzchecks use liveness checks, including event-loop responsiveness, rather than readiness-only checks. The/readyzcheck 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 outsidehealthReadyGapSlots. The container health check uses/health, not the metrics endpoint. The health listener remains available whiledingo mithril syncruns.
📝
mithril.downloadMaxTransientRetriescontrols retries for transient bootstrap download failures such as TLS timeouts, HTTP 429 responses, and HTTP 5xx responses. The example uses the default value of10.
Dingo will:
- Download the latest Mithril snapshot for your configured network
- Verify the certificate chain
- 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.yamlYou 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 the guide on creating 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.
Docs authored by Doc Holiday