A development tool that looks, acts and talks like Flow
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 service 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 service 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 service key (ie. unit tests) you can specify a hex-encoded key as an environment variable.
docker run -e FLOW_SERVICEPRIVATEKEY=<hex-encoded key> gcr.io/dl-flow/emulator
To generate a service 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_SERVICEPRIVATEKEY||optional||service account private key|
|FLOW_SERVICEPUBLICKEY||optional||service account public key|
|FLOW_SERVICEKEYSIGALGO||service account key signature algorithm|
|FLOW_SERVICEKEYHASHALGO||service 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|