Flow Developers

Flow is a fast, secure, and developer-friendly blockchain built to support the next generation of games, apps, and the digital assets that power them.

Start Here

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.

Running the emulator with the Flow CLI

The emulator is bundled with the Flow CLI, a command-line interface for working with Flow.


Follow these steps to install the Flow CLI.

Starting the server

You can start the emulator with the Flow CLI:

flow emulator start --init

This command has several useful flags:

  • -v Enable verbose logging (this is useful for debugging)
  • -p Port to listen on (default: 3569)
  • --block-time Time interval between blocks (default: 5s)
  • --persist Enable persistent storage
    (uses the Badger key-value DB)
  • --dbpath Path to store database (default: ./flowdb)

⚙️ All configuration options and flags are listed below.

Using the emulator in a project

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.

Running the emulator with Docker

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:


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

All Configuration Options

Environment VariableCLI FlagDefaultDescription
FLOW_PORT--port,-p3569port to run RPC server
FLOW_HTTPPORT--http-port3569port to run HTTP server
FLOW_VERBOSE--verbose,-vfalseenable verbose logging
FLOW_BLOCKTIME--block-time,-b5stime between sealed blocks
FLOW_ROOTPRIVATEKEY--root-priv-keyoptionalroot account private key
FLOW_ROOTPUBLICKEY--root-pub-keyoptionalroot account public key
FLOW_ROOTKEYSIGALGO--root-sig-algoECDSA_P256root account key signature algorithm
FLOW_ROOTKEYHASHALGO--root-hash-algoSHA3_256root account key hash algorithm
FLOW_INIT--initfalsewhether to initialize a new account profile
FLOW_GRPCDEBUG--grpc-debugfalseenable gRPC server reflection for debugging with grpc_cli
FLOW_PERSIST--persistfalseenable persistent storage
FLOW_DBPATH--dbpath./flowdbpath to database directory

Updated 3 months ago


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.