Practical overview
When it fits
Use it when you need a repeatable, isolated Bitcoin environment for wallet, transaction or block-generation testing without relying on the live network.
Who it is for
- Bitcoin application developers who need a local environment for testing wallet operations and transactions.
- Developers building integration tests or prototypes that interact with Bitcoin nodes through JSON-RPC.
Documented uses
- Start two isolated Bitcoin Core regtest nodes.
- Generate blocks on demand for local development scenarios.
- Create separate wallets and exercise a test transfer between them.
- Connect a test application to the nodes’ exposed JSON-RPC ports.
Requirements & limits
The primary setup is command-line based. The project documents Docker use or a non-Docker route requiring bitcoind and bitcoin-cli on the system; its repository specifies an MIT license.
- The two nodes connect only to each other, keeping the documented test network isolated.
- Regtest mode allows blocks to be generated on demand rather than waiting for live-network block intervals.
- The first wallet needs at least 100 generated blocks before it has a balance.
- The README documents JSON-RPC ports 19001 and 19011; application compatibility and authentication configuration are not detailed.
- Docker avoids the documented requirement to install bitcoind and bitcoin-cli on the host.
Check current requirements in the official documentation. Source-based guidance does not mean OpenViST has run or independently tested this project.
Start the two-node regtest environment
Launch the isolated nodes and check their status before creating wallets or testing transactions.
Before you start
- Clone the project repository.
- For a non-Docker run, have bitcoind and bitcoin-cli installed and available in the system path, using the Bitcoin Core version identified in the Dockerfile. Alternatively, use Docker.
Steps
Run make start to start the two nodes.
Run make getinfo to check node status.
For Docker, pull freewil/bitcoin-testnet-box or build the image from the repository, then run it with ports 19001 and 19011 published.
Expected outcome
Two nodes run in an isolated regtest network; the README documents JSON-RPC ports 19001 and 19011.
Guide limitations
- The guide covers starting and checking the nodes, not application-specific connection or authentication configuration.
- Docker setup is an alternative to installing bitcoind and bitcoin-cli on the host.
Create wallets and test a local transfer
Create two wallets, generate regtest blocks, and send test bitcoins from the first wallet to the second.
Before you start
- Start the two-node environment.
- Use the project’s documented bitcoin-cli commands and make targets.
Steps
Create wallet1 on node 1 and wallet2 on node 2 with bitcoin-cli -datadir=1 createwallet wallet1 and bitcoin-cli -datadir=2 createwallet wallet2.
Generate blocks with make generate; the README says at least 100 blocks are needed before the first wallet has a balance.
Get the second wallet’s address with make address2.
Send test bitcoins with make sendfrom1, supplying the generated address and an amount; generate another block and check the node status with make getinfo.
Expected outcome
A local wallet-to-wallet transaction can be exercised on the private regtest network, with block generation used to advance the scenario.
Guide limitations
- The README’s example sends 10 test bitcoins and notes that the receiving balance may not appear until another block is generated.
- This is an isolated regtest workflow, not a live-network transaction.
Sources & review
Source record details
- Source availability
- Active
- Sources checked
- 15 October 2026
- Original website title
- freewil/bitcoin-testnet-box · Official homepage title · retained in its source language