Working with a local blockchain

Clarinet provides a complete local blockchain environment, providing all the services you need for smart contract development without deploying to a public network.

Starting your local blockchain

To launch devnet with all required services, run the following command:

Terminal

$ clarinet devnet start

Option	Description
`--manifest-path <path>`	Use alternate Clarinet.toml location
`--no-dashboard`	Display logs instead of interactive UI
`--deployment-plan-path <path>`	Use specific deployment plan
`--use-on-disk-deployment-plan`	Use existing deployment plan without updates
`--use-computed-deployment-plan`	Compute and overwrite deployment plan
`--package <path>`	Use pre-packaged devnet configuration

Prerequisites

Devnet requires Docker to be running. If you see "clarinet was unable to create network", ensure Docker Desktop is running or the Docker daemon is started.

By default, devnet starts with an interactive dashboard showing:

Service status and health
Recent transactions
Block production
Contract deployments
Resource usage

Use the --no-dashboard flag for CI/CD environments or when you prefer streaming logs.

Core services and features

Devnet creates a complete blockchain environment with these services:

Service	Port	Purpose
`Stacks Node`	20443	Processes transactions and mines blocks
`Bitcoin Node`	18443	Provides block anchoring in regtest mode
`Stacks API`	3999	REST API for querying blockchain data
`Postgres DB`	5432	Indexes blockchain data for fast queries
`Stacks Explorer`	8000	Web UI for browsing transactions
`Bitcoin Explorer`	8001	Web UI for Bitcoin regtest chain

Devnet includes pre-funded accounts with STX balances:

Terminal

$ clarinet console
$ ::get_assets_maps

When devnet starts, it automatically deploys your project contracts:

Terminal

$ clarinet devnet start

Configuration and customization

Devnet behavior is controlled through configuration files in your project.

Basic configuration

The settings/Devnet.toml file controls network settings:

settings/Devnet.toml

[network]
name = "devnet"

# Service ports
stacks_node_rpc_port = 20443
stacks_api_port = 3999
stacks_explorer_port = 8000
bitcoin_node_rpc_port = 18443

# Mining configuration  
[network.devnet]
bitcoin_controller_block_time = 30_000  # 30 seconds

# Disable services you don't need
disable_bitcoin_explorer = false
disable_stacks_explorer = false
disable_stacks_api = false

Port configuration

Customize ports to avoid conflicts:

# Change default ports
stacks_node_rpc_port = 30443
stacks_api_port = 4999
postgres_port = 6432
stacks_explorer_port = 4020

Mining intervals

Control block production speed:

# Fast blocks for development (1 second)
bitcoin_controller_block_time = 1_000

# Standard testing (30 seconds)
bitcoin_controller_block_time = 30_000

# Realistic timing (2 minutes)
bitcoin_controller_block_time = 120_000

Custom accounts

Add accounts with specific balances:

Clarinet.toml

[accounts.treasury]
mnemonic = "twice kind fence tip hidden tilt action fragile skin nothing glory cousin"
balance = 10_000_000_000_000  # 10M STX

[accounts.alice]
mnemonic = "female adjust gallery certain visit token during great side clown fitness like"
balance = 5_000_000_000_000   # 5M STX

Accessing services

Access various services to interact with the blockchain, including browsing data, querying APIs, and submitting transactions directly.

Browse transactions, blocks, and contract state through the web interface:

http://localhost:8000

The explorer provides:

Transaction history and details
Block information
Contract source code and state
Account balances

Advanced configuration

Performance optimization

For fast development cycles:

settings/Devnet.toml

[network.devnet]
# 1 second blocks
bitcoin_controller_block_time = 1_000

# Disable explorers for speed
disable_bitcoin_explorer = true
disable_stacks_explorer = true

# Keep API for contract interaction
disable_stacks_api = false

Epoch configuration

Test different Stacks versions:

[epochs]
epoch_2_0 = 0     # Stacks 2.0 from genesis
epoch_2_05 = 0    # Stacks 2.05 from genesis  
epoch_2_1 = 0     # Stacks 2.1 from genesis
epoch_2_2 = 0     # Pox-2 from genesis
epoch_2_3 = 0     # Pox-3 from genesis
epoch_2_4 = 0     # Pox-4 from genesis
epoch_3_0 = 101   # Nakamoto activation at block 101

Package deployment

Create reusable devnet configurations:

Terminal

$ clarinet devnet package --name demo-env
Packaging devnet configuration...
Created demo-env.json

Use packaged configuration:

Terminal

$ clarinet devnet start --package demo-env.json

Common issues

Next steps

Now that your local development environment is running:

Learn to debug contracts using the console
Understand deployment workflows for testnet/mainnet
Explore the CLI reference for all devnet commands

Working with a local blockchain

Docker connection errors

Port already in use

High resource usage

Network already exists error

Docker stream error during startup

Contract deployment failures