> For the complete documentation index, see [llms.txt](https://docs.envio.dev/llms.txt).

## 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](https://www.docker.com/products/docker-desktop/) (or [Podman](https://podman.io/)) running.

Run the indexer

```bash
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](/docs/HyperIndex/observability#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](https://docs.envio.dev/docs/HyperIndex/environment-variables.md) 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](https://docs.envio.dev/docs/HyperIndex/testing.md) lets you mock events, simulate database state, and assert handler behavior - all without connecting to a blockchain or waiting for blocks to sync.

```bash
pnpm test
```

This is ideal for iterating on handler logic, catching bugs early, and running tests in CI. See the [Testing guide](https://docs.envio.dev/docs/HyperIndex/testing.md) 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:

```yaml
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):

```bash
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:

```bash
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](https://docs.envio.dev/docs/HyperIndex/hosted-service.md).