Running a node

ZKsync CLI provides a powerful dev command to spin up and manage ZKsync and Ethereum nodes along with Block Explorer, Wallet, and Bridge apps for a seamless local development experience.

Prerequisites

You will need Docker to setup ZKsync nodes on your local machine. Download and install Docker which will install the necessary tools for the dev command to work.

Once installed, ensure that the Docker program is running on your machine, otherwise the dev command may error. Check to make sure that the Docker Desktop is running anytime you restart your machine.

Dev modules

The dev command interacts with installed modules to manage and run systems. To view the available modules that come with ZKsync CLI, run the following command:

zksync-cli dev modules

Configuring `dev`

When you run the dev start sub-command for the first time, the CLI prompts you to select a node type and additional modules to run as default. You can also configure this with the dev config sub-command to set the default node type and modules to run.

zksync-cli dev config

Running modules

To start the modules, run the zksync-cli dev start sub-command. If you are running dev start for the first time, it will prompt you to select which modules to start. The modules will download the required packages on the first run. Subsequent starts do not need to download anything additional.

The first start may take several minutes as it will need to download the necessary packages. The CLI displays the progress and, upon successful download and start, it will return a summary of the started modules and the available ports.

In memory node started v0.1.0-alpha.25:
 - ZKsync Node (L2):
  - Chain ID: 260
  - RPC URL: http://127.0.0.1:8011
  - Rich accounts: https://docs.zksync.io/build/test-and-debug/in-memory-node#pre-configured-rich-wallets
 - Note: every restart will necessitate a reset of MetaMask's cached account data

Portal started v1.24.2:
 - Wallet: http://localhost:3000

Block Explorer started v2.48.0:
 - App: http://localhost:3010
 - HTTP API:
  - Endpoint: http://localhost:3020
  - Documentation: http://localhost:3020/docs

Managing running modules

ZKsync CLI dev modules use Docker to create Docker containers to run nodes and ZKsync apps locally. You can manage these Docker containers using the ZKsync CLI or Docker Desktop GUI. The Docker Desktop provides an easy way to manage containers, view available ports and read logs.

You can start, stop and restart modules using ZKsync CLI using the start, stop, and restart sub-commands, respectively.

The restart sub-command can take a module name as an option to restart a specific module. Otherwise it will restart all running modules.

State will not persist between stopping and starting modules.

Viewing module logs

Actively running modules have logs that can be viewed either in Docker Desktop or via ZKsync CLI. The Docker Desktop provides a more comprehensive and active view of the logs.

Run the zksync-cli dev logs to return a truncated list of logs for all actively running modules.

Cleaning modules

ZKsync CLI dev modules can be started and stopped with minimal issues and allow persistence of data between sessions. If you need to re-start with a fresh install of the modules, the zksync-cli dev clean [module name] sub-command will uninstall all of the module data from your local machine.

This sub-command deletes all data and requires reinstalling the module upon a new start.

Wallets' cached account data, like nonces, will need to be reset when you restart the ZKsync node module. Refer to Metamask's How to clear your account activity/reset account.

Creating projects

Quickly scaffold new projects using templates with ZKsync CLI create

Configuring chains

Add and manage custom chains with ZKsync CLI