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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cardonnay-0.4.6.tar.gz (104.6 kB view details)

Uploaded Sep 7, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

cardonnay-0.4.6-py3-none-any.whl (109.5 kB view details)

Uploaded Sep 7, 2026 Python 3

File details

Details for the file cardonnay-0.4.6.tar.gz.

File metadata

Download URL: cardonnay-0.4.6.tar.gz
Upload date: Sep 7, 2026
Size: 104.6 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.13.13

File hashes

Hashes for cardonnay-0.4.6.tar.gz
Algorithm	Hash digest
SHA256	`6a4cb098ebce9c40af4b4347b5d659e9a0232a7957291933a4a08d5a87741ca2`
MD5	`831f7d38bead288607aabd972a6c3841`
BLAKE2b-256	`045901f6b6baeffd1c3ce7a1b5b9f1ee1e45c72355c850a063c4e09ec81dd39a`

See more details on using hashes here.

File details

Details for the file cardonnay-0.4.6-py3-none-any.whl.

File metadata

Download URL: cardonnay-0.4.6-py3-none-any.whl
Upload date: Sep 7, 2026
Size: 109.5 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.13.13

File hashes

Hashes for cardonnay-0.4.6-py3-none-any.whl
Algorithm	Hash digest
SHA256	`c8cf324e9b6ceae227c07ab1e0faa3f38f94ab55866a87e4f1898c6b7c40966d`
MD5	`9d32ae0f8972d6b4686b0bb8693cf662`
BLAKE2b-256	`4f49aef88c2b9ff4ccaebbb0da63ee820670d2f27b2efabf12abf885f2f49faa`