The Flow Emulator is a lightweight tool that emulates the behaviour of the real Flow network.
The emulator exposes a gRPC server that implements the Flow Access API, which is designed to have near feature parity with the real network API.
The emulator is bundled with the Flow CLI, a command-line interface for working with Flow.
Follow these steps to install the Flow CLI.
You can start the emulator with the Flow CLI:
flow emulator start --init
This command has several useful flags:
-vEnable verbose logging (this is useful for debugging)
-pPort to listen on (default:
--block-timeTime interval between blocks (default:
--persistEnable persistent storage
(uses the Badger key-value DB)
--dbpathPath to store database (default:
⚙️ All configuration options and flags are listed below.
You can start the emulator in your project context by running the above command in the same directory as
flow.json. This will configure the emulator with your project's root account, meaning you can use it to sign and submit transactions.
Docker builds for the emulator are automatically built and pushed to
gcr.io/dl-flow/emulator, tagged by commit and semantic version.
In addition to using command-line flags, the emulator can also be configured with environment variables, which can be passed into the Docker image.
Here's a sample configuration:
FLOW_VERBOSE=true FLOW_PORT=3596 FLOW_BLOCKTIME=5s FLOW_PERSIST=true FLOW_DBPATH=./path/to/db
Here's how to run the emulator Docker image on port 9001 in verbose mode:
docker run -e FLOW_PORT=9001 -e FLOW_VERBOSE=true gcr.io/dl-flow/emulator
⚙️ All environment variable options are listed below.
The emulator uses a
flow.json configuration file to store persistent configuration, including account keys. In order to start, at least one key (called the root key) must be configured. This key is used by default when creating other accounts.
Because Docker does not persist files by default, this file will be re-generated each time the emulator image restarts. For situations where it is important that the emulator always uses the same root key (ie.
unit tests) you can specify a hex-encoded key as an environment variable.
docker run -e FLOW_ROOTPRIVATEKEY=<hex-encoded key> gcr.io/dl-flow/emulator
To generate a root key, use the
keys generate command in the Flow CLI.
flow keys generate
|Environment Variable||CLI Flag||Default||Description|
|FLOW_PORT||port to run RPC server|
|FLOW_HTTPPORT||port to run HTTP server|
|FLOW_VERBOSE||enable verbose logging|
|FLOW_BLOCKTIME||time between sealed blocks|
|FLOW_ROOTPRIVATEKEY||optional||root account private key|
|FLOW_ROOTPUBLICKEY||optional||root account public key|
|FLOW_ROOTKEYSIGALGO||root account key signature algorithm|
|FLOW_ROOTKEYHASHALGO||root account key hash algorithm|
|FLOW_INIT||whether to initialize a new account profile|
|FLOW_GRPCDEBUG||enable gRPC server reflection for debugging with grpc_cli|
|FLOW_PERSIST||enable persistent storage|
|FLOW_DBPATH||path to database directory|
Updated 3 months ago