How to Set Up a Local Avalanche Subnet Devnet on Fuji Testnet

08 November 2026

Setting up a local avalanche-chain/avalanche-subnet-consensus-mechanism/">Avalanche subnet devnet on Fuji testnet means configuring a private blockchain environment that runs a subnet you control, using Fuji testnet (Avalanche’s public test network) as the parent network for validation and cross-chain communication. This lets you deploy, test, and iterate on custom subnet configurations - like custom VMs, fee tokens, or validator rules - without risking real funds or affecting a production subnet on mainnet.

Prerequisites

Before starting, you will need:

• A machine running Linux or macOS with at least 8 GB of RAM, 50 GB of free disk space, and a stable internet connection.
• Go installed (version 1.18 or later recommended) to compile AvalancheGo and custom VMs.
• The Avalanche CLI tool installed. The official Avalanche documentation provides installation instructions for your operating system.
• A funded Fuji testnet wallet. You can obtain testnet AVAX from the official Avalanche faucet. The faucet URL is listed in the Avalanche developer docs.
• Basic familiarity with the terminal and command-line operations.

Step 1: Install and Configure the Avalanche CLI

The Avalanche CLI is the primary tool for creating and managing subnets. After installation, verify it works:

avalanche --version

If the command returns a version number, proceed. Otherwise, check your installation steps.

Step 2: Create a Subnet Configuration

Use the CLI to scaffold a new subnet configuration. Run:

avalanche subnet create myTestSubnet

The CLI will walk you through choices:

• VM type: You can select a custom VM (e.g., Subnet-EVM for Ethereum-compatible smart contracts) or a pre-built one. For a devnet, Subnet-EVM is common because it matches the C-Chain’s environment.
• Chain ID: Assign a unique chain ID (e.g., 12345) that does not conflict with any existing Avalanche chain or other subnet.
• Token symbol: Set the symbol for your subnet’s native gas token (e.g., “TEST”).
• Fee configuration: Decide whether to use AVAX or your subnet’s native token for gas fees. For a test devnet, using the native token is simpler.

The CLI generates a folder named myTestSubnet containing a subnet.json file and other configuration artifacts.

Step 3: Configure the Subnet for Fuji Testnet

By default, the CLI targets mainnet. To point your devnet at Fuji testnet, edit the subnet.json file or use the CLI flag --network=fuji when running commands. The key parameter is the Fuji testnet’s RPC endpoint (typically https://api.avax-test.network/ext/bc/C/rpc). The CLI handles this automatically if you specify the network.

If you are using a custom VM, ensure its binary is compiled and placed in the correct path. The CLI will ask for the VM binary location during creation.

Step 4: Deploy the Subnet to Fuji Testnet

Deploy your subnet configuration to the Fuji testnet:

avalanche subnet deploy myTestSubnet --network=fuji

This command:

1. Uploads the subnet’s VM binary to a decentralized storage network (like IPFS) or makes it accessible to validators.
2. Sends a transaction to the Fuji testnet’s Platform Chain (P-Chain) to register the subnet and its validator set.
3. Creates the subnet’s blockchain(s).

You will need to confirm the transaction using your wallet. The CLI will prompt you to import your private key or use a hardware wallet. For testnet, using a plain private key is acceptable, but keep it secure.

After deployment, the CLI outputs the subnet’s Chain ID, RPC URL, and blockchain ID. Save these.

Step 5: Start a Local Devnet Node

To run the subnet locally, you need an AvalancheGo node that connects to Fuji testnet and validates your subnet. The CLI can automate this:

avalanche node run myTestSubnet --network=fuji

This starts a single-node devnet. The node:

• Joins the Fuji testnet P-Chain.
• Downloads and runs the subnet’s VM.
• Begins validating the subnet’s blocks.

If you prefer manual control, you can configure an AvalancheGo node with a custom --subnet-config file pointing to your subnet’s blockchain ID and VM binary. The CLI’s generated subnet.json includes these details.

Step 6: Connect MetaMask or Another Wallet

To interact with your subnet devnet, add its RPC to MetaMask (or Core wallet):

1. Open MetaMask → Settings → Networks → Add Network.
2. Enter:
3. Network Name: e.g., “My Test Subnet”
4. RPC URL: The one from the deployment output (usually http://127.0.0.1:9650/ext/bc/<blockchainID>/rpc).
5. Chain ID: The one you chose (e.g., 12345).
6. Symbol: Your token symbol (e.g., TEST).
7. Save.

Your wallet now sees the subnet. To get test tokens, you may need to mint them using a simple script or the CLI’s faucet command (if supported). The CLI can generate a genesis.json file with initial token allocations.

Step 7: Deploy and Test Smart Contracts

With the wallet connected, deploy a test contract (e.g., a simple ERC-20 token) using Remix, Hardhat, or Foundry. Point your development tool to the subnet’s RPC. Transactions should be confirmed quickly because only your node is running.

Common Pitfalls

• Node sync issues: If your node fails to connect to Fuji testnet, check the network status and your internet connection. The CLI may need to download a fresh snapshot.
• VM binary errors: Ensure the VM binary is compiled for your OS and architecture. The CLI sometimes requires a pre-compiled binary in $PATH.
• Insufficient testnet AVAX: Your wallet must have enough testnet AVAX to pay for the subnet registration transaction. The faucet usually provides enough, but you may need multiple requests if you run many tests.
• RPC endpoint conflicts: If you run multiple subnets locally, each needs a unique port. The CLI handles this automatically, but manual setups must avoid port clashes.

Testing without a local node

If you do not want to run a full node, you can deploy a subnet to Fuji testnet and use its public RPC (available from the Fuji testnet’s endpoint list in Avalanche docs). However, you lose the ability to isolate your devnet environment - other testers may affect the subnet if they join.

Next Steps

After confirming your devnet works, you can:

• Add more validators by distributing your subnet’s configuration.
• Implement cross-subnet messaging using Avalanche Warp Messaging (AWM) to bridge tokens between your subnet and Fuji testnet’s C-Chain.
• Test different VM configurations or fee models.

For production-grade testing, consider using a local testnet (e.g., a standalone Avalanche network) rather than Fuji, but the process is similar.

Back to avalanche