Local devnet

Run Clarinet’s local Stacks chain with stacksdapp dev, deploy from a second terminal, and open the Next.js debug UI with Choose Wallet.

Run a local Bitcoin and Stacks chain with Docker, then point the Next.js debug UI at it. The chain, the deploy, and the frontend are three separate commands.

Contents

• Requirements
• Start the chain
• Deploy contracts
• Open the frontend
• Pre-funded accounts
• Redeploy
• Clarinet versions
• Stop and reset
• When to use devnet

Requirements

Requirement	Notes
Docker Desktop	Installed and running
Clarinet	3.23+ (Clarity 6 / epoch 4.0)
RAM	8 GB+ recommended

stacksdapp doctor

Start the chain

In the first terminal:

stacksdapp dev

This terminal is Clarinet’s devnet. Leave it running. It starts the Bitcoin node, stacks-node, and stacks-signer. It does not start Next.js, watch contract files, or deploy.

Do not run clarinet devnet start in another terminal. It uses the same ports.

--auto-deploy and --keep-state are accepted and ignored. Deploy with stacksdapp deploy. Reset a running chain with stacksdapp clean.

Deploy contracts

Wait until Clarinet is serving the chain, then in a second terminal:

stacksdapp deploy --network devnet

Devnet waits until each contract is on the local node at http://127.0.0.1:20443. It does not ask for the testnet confirmation prompt.

Open the frontend

In a third terminal, after the chain is up:

stacksdapp dev --network devnet

The app is at http://localhost:3000. This command only starts Next.js. It writes NEXT_PUBLIC_NETWORK=devnet in frontend/.env.local.

The debug UI says Choose Wallet and lists the funded devnet accounts with balances. Testnet and mainnet still use Connect Wallet (Leather or Xverse).

Browser calls go through the Next.js rewrite /devnet-node to stacks-core on port 20443. Stacks-api on port 3999 is off.

Regenerate bindings yourself when you edit contracts. stacksdapp dev does not watch files:

stacksdapp generate --watch

Pre-funded accounts

contracts/settings/Devnet.toml ships public burner accounts (deployer, wallet_1, wallet_2, wallet_3). Choose Wallet uses those keys. No real STX and no browser wallet are required.

The same file includes the PoX stacking orders the epoch 4.0 snapshot expects. Leave those orders and the epoch heights as they are.

These mnemonics are public and local-only. Never reuse them on testnet or mainnet, and never commit a real deployer seed.

Redeploy

Stacks contracts are immutable. If the name is already on this devnet, deploy versions it (counter → counter-v2 → counter-v3) and updates references. That includes a contract left on chain after you stop and start stacksdapp dev again. Clarinet keeps the chain.

stacksdapp deploy --network devnet

Fail instead of renaming:

stacksdapp deploy --network devnet --no-auto-version

stacksdapp clean resets a running devnet back to the snapshot and leaves the process up. It waits until Stacks mines a new block before it finishes, so the next deploy uses the current contract name. You do not need it for a normal redeploy.

Clarinet versions

Clarinet 3.23 or 3.24 starts stacks-node 4.0.1, which stops mining at the first PoX reward-cycle boundary after the epoch 4.0 snapshot. stacksdapp dev points that devnet at stacks-node and stacks-signer 4.0.5, keeps Clarinet’s devnet sBTC settings, stakes the devnet wallets before the next reward cycle, and mines one Bitcoin block when the chain has been quiet. Clarinet’s miner takes over once it is running.

Clarinet 3.26 and newer already ships that node. stacksdapp dev leaves the chain to Clarinet: no image pin, no extra miner, and no extra stake.

Testnet and mainnet are unchanged.

Stop and reset

Stop the chain with Ctrl+C in the stacksdapp dev terminal so Clarinet can shut its containers down.

To delete generated files and reset the local chain:

stacksdapp clean
stacksdapp clean --force

This removes frontend/src/generated, old files under contracts/.cache, and contracts/.devnet. It does not stop Docker or delete .clar sources.

When a devnet is running, clean restores that chain to Clarinet’s snapshot and leaves the Clarinet process up. It waits until Stacks mines a new block before it returns. If the tip does not move, it restarts only the signer. Wait for that to finish, then run stacksdapp deploy --network devnet. The deploy publishes the current contract name.

When no devnet is running, clean deletes the local cache so the next stacksdapp dev starts a fresh chain. Starting stacksdapp dev still stops leftover containers.

Run stacksdapp generate afterward to restore bindings.

If boot cannot grab its ports:

1. Make sure Docker is running.
2. Stop leftover containers: docker ps --filter name=devnet -q | xargs docker stop
3. Start again with stacksdapp dev.

When to use devnet

Use devnet for offline work and for trying the debug UI against a local chain. Use testnet when you want a public network, a browser wallet, and a deploy you can share.

Devnet blocks are slower than testnet because Bitcoin blocks are paced at 45 seconds so the signer can cross PoX reward cycles.