Running The Indexer Locally

Starting the Indexer

Remember to cd into your project directory if you have defined one during pnpx envio init.

Before running the Envio CLI command to start the indexer locally, make sure you have Node.js 22.15.0 or newer and Docker (or Podman) running.

Run the indexer

pnpm dev

pnpm dev runs envio dev, which runs codegen, starts Postgres and Hasura in Docker and then starts indexing. The terminal UI shows the local GraphQL (Hasura) URL, http://localhost:8080, and a link to the Dev Console. Open the Hasura console in your browser to view the indexed data.

Admin-secret / password for local Hasura is testing.

Local services and ports

envio dev starts these containers. All Envio projects on the machine share them.

Container	Image	Host port
envio-postgres	postgres:18.3	5433 (ENVIO_PG_PORT)
envio-hasura	hasura/graphql-engine:v2.43.0	8080 (HASURA_EXTERNAL_PORT)
envio-clickhouse (only with storage.clickhouse)	clickhouse/clickhouse-server:26.2.15.4	8123

The indexer itself serves metrics and health checks on 9898 (ENVIO_INDEXER_PORT). To use a Postgres or ClickHouse you run yourself, set ENVIO_PG_HOST or ENVIO_CLICKHOUSE_HOST and envio dev won't start that container. See Environment Variables for the full list.

Restarting and Code Changes

envio dev does not watch your files. After changing code, stop the indexer (Ctrl+C) and run pnpm dev again.

A restart resumes from where the indexer left off. What happens to your changes depends on what changed:

• Handler code: the new logic applies from the resume point on. Events indexed before the restart keep the results of the old logic. Run pnpm envio dev -r to re-index everything with the new logic.
• config.yaml, schema.graphql or ABIs: codegen runs again on start. If the change is incompatible with the data already indexed, such as a new entity field, a changed start_block or an added chain, the indexer stops with The following config changes are incompatible with the existing indexer data:, lists the changes and offers the fix. Run pnpm envio dev -r to delete the indexed data and start over.
• The envio version: the data records the version that indexed it, so upgrading envio also needs pnpm envio dev -r.

tip

If the indexer seems not to pick up your handler changes, check the terminal output for compilation errors from your handler files.

Avoiding Full Re-indexing During Development

Re-indexing from the start block can be slow for large datasets. Here are strategies to iterate faster:

Use the testing framework

The fastest way to validate handler logic is to skip syncing entirely. Envio's built-in testing framework lets you mock events, simulate database state, and assert handler behavior - all without connecting to a blockchain or waiting for blocks to sync.

pnpm test

This is ideal for iterating on handler logic, catching bugs early, and running tests in CI. See the Testing guide for setup and examples.

Use a recent start block

During development, temporarily set start_block in your config.yaml to a recent block number. This lets you test handler logic against fresh data without waiting for a full historical sync:

chains:
  - id: 1 # Ethereum mainnet
    start_block: 19000000 # Recent block for faster dev iteration

Remember to set it back to the correct start block before deploying to production.

Force a clean re-index

If you need to re-index from scratch (e.g., after schema changes or to clear corrupted state):

pnpm envio dev -r  # Deletes indexed data and re-indexes from start_block

Stopping the Indexer

To stop and remove the local Postgres, Hasura and ClickHouse containers and delete their data volumes, run:

pnpm envio stop

The Docker images stay cached, so the next pnpm dev starts quickly. Because the containers are shared, this also deletes the local data of any other Envio project on the machine.

What next?

Once you have successfully run the indexer locally, you can deploy the indexer onto Envio's Envio Cloud.