A terminal-based utility for Bitcoin developers who are tired of the "it works on my machine" problem. Caravan-X creates reproducible regtest environments, manages Caravan-compatible multisig wallets, and lets you share exact blockchain states with your team.
- What is Caravan-X
- Installation
- Quick Start
- Modes of Operation
- Using the TUI (Terminal User Interface)
- CLI Commands
- Configuration
- Pre-configured Test Scenarios
- Scripting Engine
- Working with Caravan
- Roadmap
- Troubleshooting
- Contributing
Caravan-X solves a real pain point in Bitcoin development: environment consistency. When you're building Bitcoin applications, testing multisig setups, or debugging transaction issues, you need everyone on your team working with the same blockchain state. Caravan-X makes this possible by:
- Spinning up identical regtest environments with Docker (or connecting to your existing node)
- Creating Caravan-compatible multisig wallets that work seamlessly with the Caravan web interface
- Packaging complete blockchain states into shareable archives
- Providing pre-built test scenarios for common patterns like RBF and CPFP
- Offering both an interactive TUI and direct CLI commands
Whether you're testing privacy analysis tools, simulating fee bumping scenarios, or just need a clean regtest environment, Caravan-X has you covered.
You'll need Node.js v22 or later. Then install globally via npm:
npm install -g caravan-xThat's it. Run caravan-x and you're off to the races.
For development (if you want to contribute or modify):
git clone https://github.com/Legend101Zz/CaravanX.git
cd CaravanX
npm install
npm run build
npm link # Makes caravan-x available globallyIf you have Docker installed and just want to get going:
caravan-x- Select "Docker Mode (Recommended)" when prompted
- Accept the default settings or customize as needed
- Wait for the Bitcoin Core container to spin up
- You're now running a fully configured regtest environment
The setup wizard handles everything: creating the container, configuring RPC authentication, setting up nginx proxy, generating initial blocks, and creating a watch-only wallet.
If you prefer managing your own node:
caravan-x- Select "Manual Mode"
- Enter your Bitcoin Core RPC connection details
- Start using all the wallet and transaction features immediately
This is the recommended approach for most developers. Docker mode automatically:
- Pulls and runs the official Bitcoin Core image (v27.0)
- Creates a dedicated Docker network for Caravan-X
- Sets up an nginx reverse proxy with CORS headers (so Caravan can talk to your node)
- Configures RPC authentication
- Generates 101 initial blocks (so you have spendable coins)
- Creates a watch-only wallet for Caravan integration
- Handles port conflicts automatically
All data is stored in ~/.caravan-x by default, but you can customize the location during setup.
What Gets Created:
~/.caravan-x/
├── config.json # Main configuration
├── docker-data/ # Bitcoin Core data directory
├── wallets/ # Caravan wallet configurations
├── keys/ # Private key storage
├── snapshots/ # Blockchain snapshots
└── scenarios/ # Custom test scenarios
Accessing Bitcoin Core:
Once Docker mode is running, your node is accessible at http://localhost:8080 (via nginx proxy). This is the URL you'll use in Caravan's settings.
For developers who want full control over their Bitcoin Core setup. You provide:
- RPC host and port (default: 127.0.0.1:18443)
- RPC username and password
- Bitcoin data directory path
Manual mode gives you access to all Caravan-X features except Docker management and nginx proxy (since you're handling that yourself).
Requirements for Manual Mode:
Your Bitcoin Core must be running in regtest mode. A minimal bitcoin.conf:
# Global settings
rpcuser=your_username
rpcpassword=your_password
server=1
# Regtest-specific settings
[regtest]
rpcport=18443Start Bitcoin Core with:
bitcoind -regtest -daemonFrom the TUI, go to Settings and select "Switch Mode." This updates your configuration and restarts Caravan-X in the new mode. Your wallet configurations and snapshots are preserved.
Launch Caravan-X without arguments to enter the interactive interface:
caravan-xYou'll see a nice ASCII banner and the main menu. Navigate with arrow keys and Enter.
The menu adapts based on your mode. In Docker mode you'll see Docker Management and Snapshots. In Manual mode you'll see the Visualization option instead.
Available in Both Modes:
- Bitcoin Wallets
- Caravan Multisig
- Transactions
- Blockchain Scripts
- Test Scenarios
- System
- Settings
- Help
Docker Mode Only:
- Docker Management
- Snapshots
Manual Mode Only:
- Visualization
Everything you need for basic wallet operations:
| Option | What It Does |
|---|---|
| List all wallets | Shows every wallet in your node with type and balance |
| Create new wallet | Makes a new wallet (regular, watch-only, or blank) |
| View wallet details | Deep dive into a specific wallet's addresses and UTXOs |
| Send funds between wallets | Move coins from one wallet to another |
| Fund wallet with regtest coins | Mine blocks directly to a wallet's address |
The heart of Caravan-X. This is where you create and manage multisig setups:
| Option | What It Does |
|---|---|
| List Caravan wallets | Shows all your multisig configurations |
| Create new Caravan multisig wallet | Interactive wizard for M-of-N setups |
| Spend from Caravan multisig wallet | Create spending transactions |
| Sign Caravan PSBT for import | Sign PSBTs and export signatures for Caravan |
| Fund Caravan multisig wallet | Send regtest coins to your multisig |
| View Caravan wallet details | See addresses, UTXOs, and configuration |
| Create watch-only wallet for Caravan | Set up address monitoring |
| Create test multisig wallets | Generate wallets with different privacy profiles |
Creating a Multisig Wallet:
The wizard walks you through:
- Choosing a name
- Selecting address type (P2WSH, P2SH-P2WSH, or P2SH)
- Setting required signatures (M) and total signers (N)
- Creating or importing signer wallets
Caravan-X generates proper sortedmulti descriptors with fingerprints and derivation paths that Caravan expects. No more descriptor format headaches.
| Option | What It Does |
|---|---|
| Create PSBT | Build a new Partially Signed Bitcoin Transaction |
| Sign PSBT | Add signatures to an existing PSBT |
| Finalize and broadcast PSBT | Complete signing and send to network |
| View transaction | Decode and inspect any transaction |
| Get raw transaction | Fetch hex for a transaction by txid |
Caravan-X includes a scripting engine for automating complex scenarios:
| Option | What It Does |
|---|---|
| Browse templates | Pre-made scripts for common patterns |
| Create new script | Start a fresh JavaScript or JSON script |
| Run script | Execute a script file |
| Manage saved scripts | View, edit, delete your scripts |
(Docker mode only)
| Option | What It Does |
|---|---|
| View container status | See if Bitcoin Core is running |
| Start container | Boot up the regtest environment |
| Stop container | Gracefully shut down |
| View logs | Check Bitcoin Core output |
| Troubleshoot port issues | Diagnose networking problems |
| Advanced options | Clean up containers, force restart |
(Docker mode only)
Save and restore complete blockchain states:
| Option | What It Does |
|---|---|
| Create Snapshot | Package current state with a name |
| List Snapshots | See all saved states with block heights |
| Restore Snapshot | Roll back to a previous state |
| Compare Snapshots | Diff two snapshots to see changes |
| Delete Snapshot | Remove old snapshots |
Run pre-configured test setups:
| Option | What It Does |
|---|---|
| List scenarios | See built-in and custom scenarios |
| Run scenario | Execute a scenario end-to-end |
| Create scenario | Build your own test scenario |
Every TUI feature is also available as a direct command. Useful for scripting and CI/CD.
# Start interactive mode (default)
caravan-x start
# List all wallets
caravan-x list-wallets
# Create a new wallet
caravan-x create-wallet --name my_wallet
caravan-x create-wallet --name my_watch --watch-only
# Fund a wallet (mine blocks to it)
caravan-x fund-wallet --name my_wallet --blocks 10
# Send between wallets
caravan-x send --from wallet_a --to wallet_b --amount 1.5
# Mine blocks
caravan-x mine --blocks 6 --wallet my_wallet# Create a multisig wallet (interactive)
caravan-x create-caravan
# List Caravan wallets
caravan-x list-caravan
# Sign a PSBT for Caravan import
caravan-x sign-caravan-psbt --file transaction.psbt --key# Run a script
caravan-x run-script --file my_scenario.js
# Run with verbose output
caravan-x run-script --file my_scenario.js --verbose
# Dry run (preview without executing)
caravan-x run-script --file my_scenario.js --dry-run
# Create a new script
caravan-x create-script --name "my_test" --type js# View system info
caravan-x system-info
# Import a Caravan wallet configuration
caravan-x import-caravan --file wallet_config.json
# Simulate blockchain activity
caravan-x simulate --blocks 5 --transactions 3Configuration lives at ~/.caravan-x/config.json. Here's what a Docker mode config looks like:
{
"mode": "docker",
"bitcoin": {
"protocol": "http",
"host": "localhost",
"port": 8080,
"user": "caravan_user",
"pass": "caravan_pass",
"dataDir": "~/.caravan-x/docker-data"
},
"docker": {
"enabled": true,
"image": "bitcoin/bitcoin:27.0",
"containerName": "caravan-x-bitcoin",
"ports": {
"rpc": 18443,
"p2p": 18444,
"nginx": 8080
}
},
"snapshots": {
"enabled": true,
"directory": "~/.caravan-x/snapshots",
"autoSnapshot": false
}
}You can edit this file directly or use the Settings menu in the TUI.
Caravan-X ships with several built-in scenarios:
Creates an unconfirmed transaction that can be replaced with a higher-fee version. Perfect for testing RBF handling in your application.
Wallets: alice (funded), bob (empty)
Transaction: alice -> bob, 1 BTC, RBF enabled, low fee
Demonstrates fee bumping via a child transaction. Creates a stuck parent transaction and a child that pays enough fee to get both confirmed.
Wallets: alice (funded), bob (empty)
Transactions:
1. alice -> bob, 5 BTC, very low fee (stuck)
2. bob -> alice, 1 BTC, high fee (bumps parent)
A ready-to-use 2-of-3 multisig configuration with initial funding.
Wallets: funder (100 BTC), multisig_2of3 (10 BTC)
Configuration: 2 signatures required, 3 total signers
For testing time-locked transactions with CSV and CLTV.
For complex testing scenarios, write scripts in JavaScript or JSON.
/**
* @name Fee Escalation Test
* @description Tests progressively increasing transaction fees
* @version 1.0.0
*/
async function runScript() {
// Create test wallets
await bitcoinService.createWallet('fee_sender', { disablePrivateKeys: false });
await bitcoinService.createWallet('fee_receiver', { disablePrivateKeys: false });
// Fund the sender
const address = await bitcoinService.getNewAddress('fee_sender');
await bitcoinService.generateToAddress(10, address);
// Create transactions at different fee rates
const feeRates = [1, 2, 5, 10, 20];
for (const rate of feeRates) {
const receiverAddr = await bitcoinService.getNewAddress('fee_receiver');
const txid = await bitcoinService.sendToAddress('fee_sender', receiverAddr, 0.1);
console.log(`Created tx at ${rate} sat/vB: ${txid}`);
}
return { success: true };
}
runScript();{
"name": "Simple Wallet Test",
"description": "Creates wallets and moves funds",
"version": "1.0.0",
"variables": {
"walletName": "test_wallet",
"fundingBlocks": 5
},
"actions": [
{
"type": "CREATE_WALLET",
"params": {
"name": "${walletName}",
"options": { "disablePrivateKeys": false }
}
},
{
"type": "MINE_BLOCKS",
"params": {
"toWallet": "${walletName}",
"count": "${fundingBlocks}"
}
}
]
}Caravan-X is designed to work seamlessly with Caravan (the web-based multisig coordinator).
- Start Caravan-X in Docker mode
- In Caravan's settings, set the Bitcoin node URL to
http://localhost:8080 - Use the same RPC credentials you configured in Caravan-X
When you create a multisig wallet in Caravan-X:
- A configuration file is saved to
~/.caravan-x/wallets/ - In Caravan, go to Wallet > Import
- Load the configuration JSON file
- Caravan will recognize the descriptors and show your addresses
- Create a spending transaction in Caravan
- Export the PSBT
- In Caravan-X, go to Caravan Multisig > Sign Caravan PSBT
- Sign with the appropriate key
- The signature JSON is copied to clipboard
- In Caravan, import the signature
Here's where Caravan-X is headed. Check marks show what's already built.
- Docker mode with automated Bitcoin Core setup
- Manual mode for existing installations
- Shared configuration format
- nginx proxy with CORS for Caravan integration
- Pre-configured test scenarios (RBF, CPFP, Multisig)
- Snapshot and restore for blockchain states
- Identical multisig wallet generation for team sharing
- Caravan-compatible descriptors (sortedmulti with proper paths)
- Privacy profile testing (good/moderate/bad wallets)
- JavaScript and JSON scripting engine
- Interactive setup wizard
- Mode-specific menus
- Improved mempool.space-style visualization
- Better transaction flow diagrams
- Real-time UTXO updates
- Basic snapshot export
- .caravan-env archive format for complete environments
- One-command environment import
- Version-controlled environment definitions
- Natural language commands via LLM integration
- Support for OpenRouter, Claude, OpenAI, Ollama
- Generate scripts from descriptions
- Automated scenario creation
Example: "Create a sequence of CPFP transactions using my multisig wallet" and the system builds and executes it.
Port Already in Use:
Caravan-X tries to handle this automatically, but if port 8080 is taken:
# Find what's using the port
lsof -i :8080
# Or let Caravan-X try a different port
# Go to Docker Management > Troubleshoot Port IssuesDocker Not Running:
Make sure Docker Desktop is running (macOS/Windows) or the Docker daemon is started (Linux).
- Verify Bitcoin Core is running:
bitcoin-cli -regtest getblockchaininfo - Check your RPC credentials match
bitcoin.conf - Ensure
server=1is set in your config - Check the port matches (default regtest RPC is 18443)
- Make sure you're using Docker mode with nginx proxy, or have CORS configured manually
- Verify the RPC URL in Caravan matches your Caravan-X setup
- Check that the watch-only wallet was created successfully
- Caravan-X uses
sortedmultiwhich requires Bitcoin Core v0.17+ - Make sure you're using descriptor wallets (not legacy)
- Check that fingerprints and derivation paths are correct
- Stop Bitcoin Core before restoring
- Ensure you have enough disk space
- Try the restore again with Docker Management > Stop Container first
Caravan-X is open source and contributions are welcome. Here's how to get involved:
- Fork the repository
- Create a feature branch
- Make your changes
- Run
npm run lintandnpm test - Submit a pull request
Areas where help is appreciated:
- Additional test scenario templates
- Improved mempool visualization
- Documentation and examples
- Bug fixes and edge case handling
Report issues at: https://github.com/Legend101Zz/CaravanX/issues
MIT License - see LICENSE file for details.
Built with care for the Bitcoin development community.