Local devnet

Run a local Stacks blockchain with Docker and stacksdapp dev — optional auto-deploy for fast Clarity smart contract iteration without testnet fees.

Run a complete Bitcoin and Stacks development environment locally with Docker.

Contents

• Requirements
• Start devnet
• Auto-deploy
• Pre-funded accounts
• Development workflow
• Stop devnet
• When to use devnet
• Limitations

Requirements

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

Verify with:

stacksdapp doctor

Start devnet

stacksdapp dev

This starts:

• Bitcoin node
• Stacks node
• Frontend at http://localhost:3000
• File watcher for auto-regeneration
• Chain health monitoring (prefixed [dev] logs)

Deploy contracts in a second terminal once the node is ready (~30s):

stacksdapp deploy --network devnet

Do not run clarinet devnet start alongside stacksdapp dev. They conflict on ports.

Auto-deploy

Deploy once the local chain is healthy. No second terminal required.

stacksdapp dev --auto-deploy

The supervisor waits for the devnet node, then runs deploy automatically. Recommended for reliable local deploy verification.

Preserve devnet cache between runs:

stacksdapp dev --keep-state

Pre-funded accounts

Devnet includes pre-funded accounts in contracts/settings/Devnet.toml:

[accounts.deployer]
mnemonic = "twice kind fence tip hidden tilt action fragile skin nothing glory cousin green tomorrow spring wrist shed math olympic multiply hip blue scout claw"
balance = 100_000_000_000_000

[accounts.wallet_1]
mnemonic = "sell invite acquire kitten bamboo drastic jelly vivid peace spawn twice guilt pave pen trash pretty park cube fragile unaware remain midnight betray rebuild"
balance = 100_000_000_000_000

The devnet settings also include PoX stacking orders required for the epoch 4.0 snapshot. Do not remove them or override epoch heights.

These are public burner mnemonics for local use only. The settings file includes a CLI warning. Never reuse them on testnet or mainnet, and never commit real deployer seeds.

No real STX or external wallet is required for basic debug UI flows on devnet.

Development workflow

• Edit .clar files. Bindings regenerate automatically.
• ABI cache in contracts/.cache/ skips unchanged work.
• Deploy with --auto-deploy or stacksdapp deploy --network devnet.
• Test with pre-funded accounts.

After contract changes on devnet, set NEXT_PUBLIC_NETWORK=devnet in frontend/.env.local. If you deployed to testnet instead, use stacksdapp dev --network testnet.

Stop devnet

stacksdapp clean
stacksdapp clean --force    # skip confirmation

Stops services and removes generated and devnet state.

If devnet boot stalls:

1. Ensure Docker is running
2. Stop conflicting containers: docker ps --filter name=devnet -q | xargs docker stop
3. stacksdapp clean --force
4. Retry stacksdapp dev --auto-deploy

When to use devnet

• Complex multi-contract interactions
• Bitcoin-specific features (sBTC, block data)
• Offline development
• Full stack simulation

For deploy verification, testnet is more reliable than long-running local devnet.

Limitations

• Slower than testnet (Docker overhead)
• No real economic incentives
• Limited to local machine
• Long idle devnet sessions can stall around Stacks block ~71 (PoX / signer timeout). Prefer --auto-deploy or use testnet for deploy verification
• Devnet bitcoin_controller_block_time is set to 45s to allow Nakamoto signer time through PoX reward-cycle transitions