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.8

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.8
File	Size	Uploaded
cardonnay-0.4.8.tar.gz	107.8 kB	Oct 1, 2026	Details

Built distribution (wheel)

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

Total release size: 219.8 kB

Release files / cardonnay-0.4.8.tar.gz

Download URL	cardonnay-0.4.8.tar.gz
Size	107.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`d551579db14714959ad844b1ad0100bdcf8a5e66c2954b24ee3175c01e08d7b6`
BLAKE2b-256 checksum How to use checksums	`80df593df1d76933d19e5d138cd7031fa7adcec6aa8256c8f74ca41d2219358d`
Upload date	Oct 1, 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.8-py3-none-any.whl

Download URL	cardonnay-0.4.8-py3-none-any.whl
Size	112.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`c74c59b427669ffa271359ebb63f64c3910d8f3cc8d770d6e94ff347e0780905`
BLAKE2b-256 checksum How to use checksums	`3c445415ffa333ca8b56274fdec2a8b56dc318b6a92ff39ea9ce91461806ecc3`
Upload date	Oct 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.7`