Environment Variables

Environment variables are a crucial part of configuring your Envio blockchain indexer. They allow you to manage sensitive information and configuration settings without hardcoding them in your codebase.

Naming Convention

HyperIndex reads the variables listed below. Most start with ENVIO_; the logging and Hasura ones keep their own names.

Your own variables (RPC URLs, API keys) can use any name locally, both in config.yaml and in handler code. Envio Cloud only accepts variables prefixed with ENVIO_, so use the prefix for anything you deploy.

Envio API Token (required for HyperSync)

To ensure continued access to HyperSync, set an Envio API token in your environment.

• Use ENVIO_API_TOKEN to provide your token at runtime
• See the API Tokens guide for how to generate a token: API Tokens
• A token is only required when using Envio as the data provider (HyperSync). Indexers that source data from an external RPC don't need one.

Envio-specific environment variables

The following variables are used by HyperIndex. Defaults marked "dev" apply only while NODE_ENV is not production (see Production mode).

General

Variable	Default	Description
ENVIO_API_TOKEN	-	API token for HyperSync (required when any chain uses HyperSync - get one at envio.dev/app/api-tokens). envio init also reads it in place of --api-token.
ENVIO_CONFIG	config.yaml	Config file path, relative to the project directory. Same as the CLI's --config flag.
ENVIO_INDEXER_PORT	9898	Port of the indexer's HTTP server, which serves /metrics, /metrics/runtime and /healthz - see Observability
ENVIO_TUI	auto	false disables the terminal UI, true forces it on (replaces the V2 TUI_OFF=true flag). Without it, the TUI is off when stdout is not a terminal, in CI (CI set), under Claude Code (CLAUDECODE set) or with TERM=dumb.
ENVIO_HASURA	true	false skips Hasura: envio dev doesn't start the container and the indexer doesn't track tables

Postgres

Variable	Default	Description
ENVIO_PG_HOST	localhost (dev)	Postgres host. Setting it at all tells envio dev you run Postgres yourself, so it doesn't start a container.
ENVIO_PG_PORT	5433 (dev)	Postgres port. For envio dev it is the host port of the container, which itself always listens on 5432.
ENVIO_PG_USER	postgres (dev)	Postgres username
ENVIO_PG_PASSWORD	testing	Postgres password
ENVIO_PG_DATABASE	envio-dev (dev)	Postgres database name
ENVIO_PG_SCHEMA	public	Postgres schema the indexer writes to (replaces ENVIO_PG_PUBLIC_SCHEMA; the old name is still accepted until v4). Give each indexer sharing a database its own schema.
ENVIO_PG_SSL_MODE	false (dev)	true, false, require, allow, prefer or verify-full
ENVIO_PG_MAX_CONNECTIONS	2	Postgres connection budget for the whole run. With 4 or more, an indexer whose entities are all per-chain (no @crossChain entity) splits its chains across up to 4 worker processes, with at least 2 connections each.

Hasura

Variable	Default	Description
HASURA_GRAPHQL_ENDPOINT	http://localhost:8080/v1/metadata (dev)	Hasura metadata endpoint the indexer uses to track tables
HASURA_GRAPHQL_ADMIN_SECRET	testing (dev)	Hasura admin secret. envio dev also sets it on the container it starts.
HASURA_GRAPHQL_ROLE	admin (dev)	Role used for metadata calls
HASURA_EXTERNAL_PORT	8080	Host port of the Hasura container started by envio dev
ENVIO_HASURA_RESPONSE_LIMIT	none	Maximum rows the public role can read per query (old name HASURA_RESPONSE_LIMIT still works)
ENVIO_HASURA_PUBLIC_AGGREGATE	[]	JSON array of entity names whose aggregate queries are open to the public role, e.g. ["Transfer","Account"]

ClickHouse

When the indexer also writes to ClickHouse (storage.clickhouse in config.yaml), envio start reads the connection from ENVIO_CLICKHOUSE_HOST (a URL such as http://localhost:8123), ENVIO_CLICKHOUSE_DATABASE, ENVIO_CLICKHOUSE_USERNAME and ENVIO_CLICKHOUSE_PASSWORD, plus the optional ENVIO_CLICKHOUSE_REPLICATED (only true is accepted) and ENVIO_CLICKHOUSE_DATABASE_ENGINE for high-availability setups. envio dev spins up its own container and injects these for you, using the default user with no password and the default database. Setting ENVIO_CLICKHOUSE_HOST makes envio dev use your server instead.

Logging

LOG_LEVEL, FILE_LOG_LEVEL, LOG_STRATEGY and LOG_FILE control logging. See Logs for their values.

Tuning

These rarely need changing. The defaults are for v3.14 and can change between releases.

Variable	Default	Description
ENVIO_HYPERSYNC_CLIENT_TIMEOUT_MILLIS	120000	HyperSync request timeout
ENVIO_HYPERSYNC_CLIENT_ENABLE_QUERY_CACHING	true	HyperSync client query caching
ENVIO_HYPERSYNC_CLIENT_SERIALIZATION_FORMAT	CapnProto	CapnProto or Json
ENVIO_HYPERSYNC_LOG_LEVEL	info	HyperSync client log level: trace, debug, info, warn or error
ENVIO_RPC_INITIAL_BLOCK_INTERVAL, ENVIO_RPC_BACKOFF_MULTIPLICATIVE, ENVIO_RPC_ACCELERATION_ADDITIVE, ENVIO_RPC_INTERVAL_CEILING	-	Override the matching RPC option for every RPC, taking precedence over config.yaml
ENVIO_INDEXING_MAX_BUFFER_SIZE	100000	Target number of fetched items buffered across all chains
ENVIO_IN_MEMORY_OBJECTS_TARGET	100000	In-memory changes the indexer holds before processing waits for writes to catch up
MAX_PARTITION_SIZE	5000	Addresses per query partition for a contract
ENVIO_CLIENT_FILTER_ADDRESS_THRESHOLD	250000	Registered addresses after which a contract's events are filtered by address in the indexer instead of in the query
ENVIO_THROTTLE_CHAIN_METADATA_INTERVAL_MILLIS	500 (dev)	How often chain metadata (_meta) is written
ENVIO_THROTTLE_PRUNE_STALE_DATA_INTERVAL_MILLIS	30000 (dev)	How often entity history outside the reorg window is pruned

Production mode

When NODE_ENV=production, the "dev" defaults above are switched off and the indexer refuses to start until they are set, printing Missing environment variables: with the list. Set ENVIO_PG_HOST, ENVIO_PG_PORT, ENVIO_PG_USER, ENVIO_PG_DATABASE, ENVIO_PG_SSL_MODE, HASURA_GRAPHQL_ENDPOINT, HASURA_GRAPHQL_ROLE, HASURA_GRAPHQL_ADMIN_SECRET, ENVIO_THROTTLE_CHAIN_METADATA_INTERVAL_MILLIS and ENVIO_THROTTLE_PRUNE_STALE_DATA_INTERVAL_MILLIS. The three Hasura variables are needed even with ENVIO_HASURA=false; a missing HASURA_GRAPHQL_ENDPOINT fails with TypeError: Cannot read properties of undefined (reading 'slice'). Without NODE_ENV=production, the defaults apply.

note

The V2 variables MAX_BATCH_SIZE, ENVIO_INDEXING_BLOCK_LAG, UNORDERED_MULTICHAIN_MODE, and UNSTABLE__TEMP_UNORDERED_HEAD_MODE have been removed in V3. Use the full_batch_size config option in config.yaml instead of MAX_BATCH_SIZE, and use the per-chain block_lag option instead of ENVIO_INDEXING_BLOCK_LAG. Unordered multichain processing is now the default.

Example Environment Variables

Here are some commonly used environment variables:

# Envio API Token (required for HyperSync access)
ENVIO_API_TOKEN=your-secret-token

# Blockchain RPC URL
ENVIO_RPC_URL=https://arbitrum.direct.dev/your-api-key

# Coingecko API key
ENVIO_COINGECKO_API_KEY=api-key

# Disable the terminal UI
ENVIO_TUI=false

Setting Environment Variables

Local Development

For local development, you can set environment variables in several ways:

1. Using a .env file in your project root:

# .env
ENVIO_API_TOKEN=your-secret-token
ENVIO_RPC_URL=https://arbitrum.direct.dev/your-api-key

2. Directly in your terminal:

export ENVIO_API_TOKEN=your-secret-token
export ENVIO_RPC_URL=https://arbitrum.direct.dev/your-api-key

Envio Cloud

When using Envio Cloud, you can configure environment variables through the Envio platform's dashboard. Variables you set there must be prefixed with ENVIO_.

For more information about environment variables in Envio Cloud, see the Envio Cloud documentation.

Configuration File

For use of environment variables in your configuration file, read the docs here: Configuration File.

Best Practices

1. Never commit sensitive values: Always use environment variables for sensitive information like API keys and database credentials
2. Never commit or use private keys: Never commit or use private keys in your codebase
3. Use descriptive names: Make your environment variable names clear and descriptive
4. Document your variables: Keep a list of required environment variables in your project's README
5. Use different values: Use different environment variables for development, staging, and production environments
6. Validate required variables: Check that all required environment variables are set before starting your blockchain indexer

Troubleshooting

If you encounter issues with environment variables:

1. Verify that all required variables are set. A variable used in config.yaml but not set fails codegen with Failed to interpolate variables into your config file. Environment variables are not present: <NAME>.
2. On Envio Cloud, check that your own variables are prefixed with ENVIO_
3. Ensure there are no typos in variable names
4. Confirm that the values are correctly formatted. An invalid value stops the indexer with Invalid environment variables: and the reason.

For more help, see our Observability Guide.