Skip to main content
Now that we understand what a localnet is, let’s walk through the complete workflow of running it and testing it with a simple smart contract and a frontend application. For this tutorial, we’ll use near-sandbox, since it’s the easiest and fastest option to start with. Our goal for this tutorial is to set up a local network, create a wallet account on it, deploy a contract, and finally run a frontend application that interacts with this contract directly through the local blockchain.
Also check the localnet tutorial by the NEAR MPC team

​
Prerequisites

Before we begin, make sure you have a few essential tools installed.
  • NEAR CLI - the CLI for interacting with the NEAR blockchain;
  • cargo-near - the CLI that simplifies building/deploying Rust smart contracts.

​
Walkthrough

​
Step 1. Setup and boot up sandbox node

First, run the following command:
This command prepares a fresh configuration inside the home folder, which is /tmp/near-sandbox in the command above. Once it’s finished, you’ll find several files created in that directory:
  • config.json - main node configuration, defining network ports, storage paths, runtime settings, etc
  • genesis.json - defines the initial blockchain state, including default account near and the validator account (by default, it’s test.near)
  • validator_key.json - validator’s keypair used to produce blocks
  • node_key.json - keypair used for signing network packets
This initialization process is a one-time setup. Once the configuration is in place, you can start and stop the node as many times as you like, the blockchain state will persist inside this folder. After initialization, start the node:
The node will boot up and begin producing blocks locally.
If the node fails to start with IO error: While lock file: .../data/LOCK: Resource temporarily unavailable, it means another sandbox process was previously running and left a stale lock. Kill any running sandbox processes and remove the lock file:
Then run the npx near-sandbox ... run command again.
To confirm that your node is actually running, you can query its status RPC endpoint with the following command curl http://127.0.0.1:3030/status.

​
Step 2. Import test.near account

In this step, we’ll import the default test.near account that was created during near-sandbox initialization. We’ll need this account later to deploy our smart contract, so let’s prepare it now. First, make sure your near-cli-rs knows how to connect to your local network. If you already have a localnet configuration, you can skip this step. Otherwise, you have two options:
The CLI will ask 8 questions. Answer as follows for a basic localnet setup:
The wallet_url and explorer_transaction_url are set to placeholder values since no local wallet or explorer is running. For a full description of all available connection fields and when each one is needed, see the Localnet configuration values section in the CLI reference.
To confirm that the connection was set up correctly, you can view information about the test.near account with the following command near account view-account-summary test.near network-config localnet-sandbox now.
When you initialized the near-sandbox, it created a file named validator_key.json inside the home directory. This file contains the secret key for the test.near account, which we’ll need to import into near-cli-rs. To view the key, run:
You’ll see output similar to this:
Copy the secret_key value and import it into near-cli-rs by running the following command (replace <SECRET_KEY> with the actual key):
When you run the command above, you’ll be prompted to enter the account ID. Type test.near and press Enter. You’ll then be asked to choose a keychain for storing the credentials, select Legacy Keychain, as it stores the keys directly in the file system, which is the simplest and the most convenient option for localnet.

​
Step 3. Deploy the smart contract

In this step, we’ll deploy a simple Hello World smart contract to our localnet. Before deploying, we need to create an account to which a contract will be deployed. Since we’ve already imported the test.near account, we can use it as the parent account to create a new subaccount:
This command creates a new account named hello-world.test.near with an initial balance of 10 NEAR. Next, clone the Hello World repository and navigate to the contract directory:
Once you’re inside the repository, run the following command:
This command compiles the smart contract, optimizes the resulting .wasm file, and deploys it directly to the hello-world.test.near account on localnet.
To verify that the contract was deployed successfully, call get_greeting directly: near contract call-function as-read-only hello-world.test.near get_greeting json-args '{}' network-config localnet-sandbox now. If it returns "Hello", the contract is running correctly.

​
Step 4. Create user’s wallet account

In this step, we’ll create a user account inside a wallet that can connect to our localnet. This is important because frontend applications typically interact with contracts through a wallet connection. Not every NEAR wallet supports localnet connections, but for this tutorial, we’ll use Intear Wallet, which is fully compatible.\ Navigate to https://wallet.intear.tech. If you don’t have an account yet, create one or import any existing account. It doesn’t matter which one, this step is just to get you inside the wallet interface. Once you’re in the wallet, open the Settings panel from the sidebar, then find the Developer tab. You’ll see a Localnet subsection where you can add your own local network configuration. Click Add, and fill in the fields as follows: set the RPC URL to http://localhost:3030 and the Network ID to localnet. Then click Save. If everything is configured correctly, you should see a small, green Online badge appear next to the new network indicating that it’s connected. Here’s how it should look like: Preview Next, click the Control button on the right side of the localnet entry. Find the Create New Account section, type a name for your new account (in our case, it’s user.local) and click Create. Once the request goes through, the new account will appear in your wallet. At this point, you have a valid account on your localnet that can sign transactions through Intear Wallet.

​
Step 5. Spin up and interact with frontend application

Start by cloning the repository:
Once you’re inside the repository, install the dependencies using pnpm:
Next, create a .env.local file to point the app at your local node:
Then, start the development Next.js server:
Navigate to http://localhost:3000/hello-near, and at the top-right corner, click Login. When prompted to select a wallet, choose Intear Wallet, Web version. And make sure you connect using the account created earlier, in our case, it’s user.local. Once connected, you’ll see an input field and a button to update the greeting. Type any new greeting into the input and click Save. You’ll be redirected to the wallet to approve a transaction. Once approved, the transaction will be sent and executed on localnet node. Return to the frontend and notice that the greeting has changed.

​
Step 6. (Optional) Stream blocks with NEAR Indexer

So far our localnet has been producing blocks silently. In this step, we’ll attach the NEAR Indexer to the same localnet so we can observe every block, transaction, and receipt in real time, which is useful for building back-ends, analytics, or end-to-end tests that react to on-chain events. The indexer is essentially a neard node with extra streaming features, so we can point it at the same home directory the sandbox is already using (/tmp/near-sandbox). That way it joins our localnet as the node itself, reusing genesis.json, validator_key.json, node_key.json and config.json, no extra network setup required.
The NEAR Indexer Framework only works on Linux x86, it does not support Windows or MacOS. If you are on another platform, skip this step or run the indexer inside a Linux x86 container/VM that can reach the sandbox home directory.
First, stop the running sandbox node with Ctrl+C. Two processes can’t share the same home directory, so the indexer will take its place as the localnet node. Next, clone nearcore and build the indexer example:
Then start the indexer pointing at the sandbox home directory:
The indexer will boot up using the existing localnet state and begin streaming finalized blocks to its handler. You’ll see block data printed to stdout as new blocks are produced.
With the indexer running, open a new terminal and trigger a transaction against your contract (for example, calling set_greeting from the frontend or from near-cli-rs). The corresponding block, transaction, and receipts will appear in the indexer’s output almost immediately.
To learn how to parse the streamed block data, filter by accounts or shards, and tweak sync/finality settings, head over to the full Creating an Indexer tutorial.
You’ve now gone through the entire process of setting up a local NEAR environment — from running the Sandbox and deploying a contract to connecting a wallet, interacting with it through a frontend, and streaming on-chain events with the NEAR Indexer. With this setup, you can experiment freely, test your contracts safely, and build end-to-end decentralized applications without touching mainnet or testnet.