Cardonnay

Cardonnay logo

Cardonnay is a command-line tool for setting up and managing local Cardano testnets.
It supports multiple preconfigured testnet types and makes it easy to inspect and control their lifecycle.

🚀 Getting Started

1. Create a `local_fast` testnet

$ cardonnay create
Starting the testnet cluster with `/var/tmp/cardonnay-of-user/cluster0_local_fast/start-cluster`:
[...]
Cluster started 🚀

ℹ️ Pro Tip: Add -b to create the testnet in the background, or -c "comment" to add a comment.

2. List running testnet instances

$ cardonnay control ls

[
  {
    "instance": 0,
    "type": "local_fast",
    "state": "started",
    "comment": null
  }
]

3. Inspect the testnet faucet

$ cardonnay inspect faucet -i 0

{
  "address": "addr_test1vpgm9cj9u3k63642vju9jqgeqy393upttt0qtwptlesy08gx620qd",
  "vkey_file": "/var/tmp/cardonnay-of-user/state-cluster0/shelley/genesis-utxo.vkey",
  "skey_file": "/var/tmp/cardonnay-of-user/state-cluster0/shelley/genesis-utxo.skey"
}

4. Work with the testnet

source <(cardonnay control print-env -i 0)
cardano-cli query tip --testnet-magic 42

5. Stop all running testnet instances

$ cardonnay control stop-all
Stopping the testnet cluster with `/var/tmp/cardonnay-of-user/state-cluster0/stop-cluster`:
[...]
Cluster terminated!

🛠️ Installation

Option 1: Using Nix

If you use Nix, you can spin up a development shell with all dependencies:

nix develop

This will provide a fully set-up environment, including Python, Cardano binaries, and jq.

ℹ️ NOTE: To use the latest master branch of cardano-node, run

nix flake update --accept-flake-config --override-input cardano-node github:IntersectMBO/cardano-node/master
nix develop --accept-flake-config

Option 2: Using `make`

Ensure the following dependencies are installed and available in your PATH:

python3
jq
cardano-node
cardano-cli
optional: cardano-submit-api

Then install Cardonnay into a virtual environment (.venv) and activate it:

# Create the virtual environment and install Cardonnay
make install

# Activate the virtual environment
source .venv/bin/activate

# (Optional) Enable shell completions for Bash
source completions/cardonnay.bash-completion

⚙️ db-sync (optional)

db-sync is started automatically when DBSYNC_SCHEMA_DIR points to the cardano-db-sync schema directory (cardano-db-sync must be on your PATH). It stays off otherwise.

Set these env vars before cardonnay create:

Env var	Effect
`DBSYNC_SCHEMA_DIR`	Path to the db-sync schema dir; enables db-sync.
`SMASH`	Truthy (`1`/`true`/`yes`/`on`) also starts a SMASH server.
`DBSYNC_ALLOW_PRIVATE_OFFCHAIN_URLS`	Truthy lets db-sync fetch off-chain anchor data (pool/governance metadata) served from `localhost`. Needed on a local testnet; off by default.

export DBSYNC_SCHEMA_DIR=/path/to/cardano-db-sync/schema
export DBSYNC_ALLOW_PRIVATE_OFFCHAIN_URLS=true
cardonnay create

Metadata

Release files for cardonnay 0.4.9

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cardonnay 0.4.9
File	Size	Uploaded
cardonnay-0.4.9.tar.gz	108.3 kB	Oct 9, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for cardonnay 0.4.9
File	Interpreter	ABI	Platform	Reset
cardonnay-0.4.9-py3-none-any.whl 112.5 kB Oct 9, 2026	Python 3	none	any	Details

Total release size: 220.9 kB

Release files / cardonnay-0.4.9.tar.gz

Download URL	cardonnay-0.4.9.tar.gz
Size	108.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`3e7c02c1f3d4444397b24711a70a94f3a38dfea12b43feb18dcf8ea40ad4d0ab`
BLAKE2b-256 checksum How to use checksums	`dde68194584425670f7475a8f809464c51bea19e0f4a0105d722a1cc6a182108`
Upload date	Oct 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.7`

Release files / cardonnay-0.4.9-py3-none-any.whl

Download URL	cardonnay-0.4.9-py3-none-any.whl
Size	112.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`544608347c73b1458f88e995258bb9c6641be4c935dc9102b12a220a3b0224c5`
BLAKE2b-256 checksum How to use checksums	`167726440d25e7c6ed9c3dabe6a96fbf5505fb65e3c911f60dbdd8129d39674a`
Upload date	Oct 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.7`