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 -t local_fast
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 `pip`

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

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

Then install Cardonnay in a virtual environment:

# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install Cardonnay
pip install -U --require-virtualenv cardonnay

# (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 -t local_fast

Metadata

Release files for cardonnay 0.4.7

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.7
File	Size	Uploaded
cardonnay-0.4.7.tar.gz	106.1 kB	Sep 22, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for cardonnay 0.4.7
File	Interpreter	ABI	Platform	Reset
cardonnay-0.4.7-py3-none-any.whl 110.4 kB Sep 22, 2026	Python 3	none	any	Details

Total release size: 216.5 kB

Release files / cardonnay-0.4.7.tar.gz

Download URL	cardonnay-0.4.7.tar.gz
Size	106.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`e2f09ca9211105ca5ec3f4684dc279e73bdfd9c39fbfbfbd4a51923df36f50fd`
BLAKE2b-256 checksum How to use checksums	`7155c4f4a440e3da9f3723cb9dad14e4f39f3e79463fdf07ef5d1040bb5a711f`
Upload date	Sep 22, 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.7-py3-none-any.whl

Download URL	cardonnay-0.4.7-py3-none-any.whl
Size	110.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`257ff4b1e5984b32d14dab025f2207cfbb8b303c67cbab5b0f4cb007e701a4bb`
BLAKE2b-256 checksum How to use checksums	`1e82431060beb5acb7b490ba6302b596da74a27ea596ead61ffd96d24709ca74`
Upload date	Sep 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.7`