Environment Variables

Default Values: Most environment variables have sensible defaults. Only set variables when you need to override the default behavior.

Core ar.io Node

The main ar.io Gateway service that handles data retrieval, indexing, and serving.

Server Configuration

Variable	Type	Default	Description
`PORT`	number	`4000`	HTTP server port
`NODE_ENV`	string	`production`	Node.js environment
`LOG_LEVEL`	string	`info`	Logging level (error, warn, info, debug)
`LOG_FORMAT`	string	`simple`	Log format (simple, json)
`LOG_FILTER`	string	`{"always":true}`	Log filtering configuration
`LOG_ALL_STACKTRACES`	boolean	`false`	Include full stack traces in logs
`INSTANCE_ID`	string	-	Unique instance identifier

Authentication & Security

Variable	Type	Default	Description
`ADMIN_API_KEY`	String	Generated	API key for admin endpoints (auto-generated if not set)
`ADMIN_API_KEY_FILE`	String	-	Path to file containing admin API key

HTTP Message Signatures (RFC 9421)

Configure response signing to provide cryptographic proof that your gateway produced a given response.

If OBSERVER_KEYPAIR_PATH or OBSERVER_PRIVATE_KEY is set, the observer's Ed25519 Solana key signs responses directly. The key's Solana address is already in the on-chain Gateway Registry, so verifiers can confirm the signer with a single GAR lookup. If neither is set, the gateway auto-generates a standalone Ed25519 key at HTTPSIG_KEY_FILE; responses are still signed but can't be tied back to the registry. Setting both at once is rejected at startup as ambiguous.

Variable	Type	Default	Description
`HTTPSIG_ENABLED`	boolean	`false`	Enable RFC 9421 response signing
`HTTPSIG_KEY_FILE`	string	`data/keys/httpsig.pem`	Path to standalone Ed25519 private key PEM. Auto-generated on first startup if missing. Ignored when `OBSERVER_KEYPAIR_PATH` or `OBSERVER_PRIVATE_KEY` is set
`HTTPSIG_BIND_REQUEST`	boolean	`true`	Include request method and path in signature (prevents replay)
`OBSERVER_KEYPAIR_PATH`	string	-	Path to a 64-byte Solana keypair JSON file (e.g. `solana-keygen new` output). When set, used as the HTTPSIG signing key
`OBSERVER_PRIVATE_KEY`	string	-	Alternative to `OBSERVER_KEYPAIR_PATH`: base58-encoded 64-byte Solana secret key (the format Phantom and other browser wallets export)

Network Configuration

Variable	Type	Default	Description
`TRUSTED_NODE_URL`	string	`https://turbo-gateway.com`	Trusted Arweave node URL
`TRUSTED_GATEWAY_URL`	string	`https://turbo-gateway.com`	Primary trusted gateway URL
`TRUSTED_GATEWAYS_URLS`	JSON	`{"https://turbo-gateway.com": 1}`	Weighted trusted gateway URLs
`TRUSTED_GATEWAYS_REQUEST_TIMEOUT_MS`	number	`10000`	Request timeout for trusted gateways
`ARWEAVE_NODE_IGNORE_URLS`	string	-	Comma-separated URLs to ignore

Chunk Management

Variable	Type	Default	Description
`CHUNK_POST_URLS`	string	`https://turbo-gateway.com/chunk`	URLs for posting chunks
`CHUNK_POST_CONCURRENCY_LIMIT`	number	`2`	Max concurrent chunk posts
`CHUNK_POST_MIN_SUCCESS_COUNT`	number	`3`	Min successful chunk posts required
`CHUNK_POST_RESPONSE_TIMEOUT_MS`	number	-	Chunk POST response timeout
`CHUNK_POST_ABORT_TIMEOUT_MS`	number	-	Chunk POST abort timeout
`SECONDARY_CHUNK_POST_URLS`	string	-	Secondary chunk POST URLs
`SECONDARY_CHUNK_POST_CONCURRENCY_LIMIT`	number	`2`	Secondary chunk POST concurrency
`SECONDARY_CHUNK_POST_MIN_SUCCESS_COUNT`	number	`1`	Secondary chunk POST success count

Data Sources

Variable	Type	Default	Description
`ON_DEMAND_RETRIEVAL_ORDER`	string	`s3,trusted-gateways,chunks,tx-data`	On-demand data retrieval priority
`BACKGROUND_RETRIEVAL_ORDER`	string	`chunks,s3,trusted-gateways,tx-data`	Background data retrieval priority
`CHUNK_DATA_SOURCE_TYPE`	string	`fs`	Chunk data source type (fs, legacy-s3)
`CHUNK_METADATA_SOURCE_TYPE`	string	`fs`	Chunk metadata source type (fs, legacy-psql)

CDB64 Root Transaction Index

The CDB64 index provides O(1) constant-time lookups for resolving data item IDs to their root Arweave transactions. As of Release 67, a pre-built index is enabled by default covering ~964 million records.

Variable	Type	Default	Description
`ROOT_TX_LOOKUP_ORDER`	string	`db,gateways,cdb,graphql`	Comma-separated list of root TX lookup sources. Options: db, cdb, gateways, turbo, graphql
`CDB64_ROOT_TX_INDEX_SOURCES`	string	shipped manifest	Comma-separated list of CDB64 sources: local paths, directories, HTTP URLs, Arweave TX IDs, or bundle data items
`CDB64_ROOT_TX_INDEX_WATCH`	boolean	`true`	Enable file watching for local CDB64 directories. New files auto-load without restart
`CDB64_REMOTE_RETRIEVAL_ORDER`	string	`gateways,chunks`	Data sources for fetching remote CDB64 files. Options: gateways, chunks, tx-data
`CDB64_REMOTE_CACHE_MAX_REGIONS`	number	`100`	Maximum byte-range regions to cache per remote source
`CDB64_REMOTE_CACHE_TTL_MS`	number	`300000`	TTL for cached byte-range regions (5 minutes)
`CDB64_REMOTE_REQUEST_TIMEOUT_MS`	number	`30000`	Request timeout for remote CDB64 sources
`CDB64_REMOTE_MAX_CONCURRENT_REQUESTS`	number	`4`	Maximum concurrent HTTP requests across all remote CDB64 sources
`CDB64_REMOTE_SEMAPHORE_TIMEOUT_MS`	number	`5000`	Maximum wait time for a request slot before failing

For detailed configuration and usage, see CDB64 Root TX Index.

Indexing & Synchronization

Variable	Type	Default	Description
`START_WRITERS`	boolean	`true`	Enable indexing processes
`START_HEIGHT`	number	`0`	Starting block height for indexing
`STOP_HEIGHT`	number	`Infinity`	Stopping block height for indexing
`SKIP_CACHE`	boolean	`false`	Bypass header cache
`SIMULATED_REQUEST_FAILURE_RATE`	number	`0`	Rate of simulated request failures

ANS-104 Bundle Processing

Variable	Type	Default	Description
`ANS104_UNBUNDLE_FILTER`	JSON	`{"never": true}`	Filter for bundles to unbundle
`ANS104_INDEX_FILTER`	JSON	`{"never": true}`	Filter for data items to index
`ANS104_UNBUNDLE_WORKERS`	number	`1`	Number of unbundling workers
`ANS104_DOWNLOAD_WORKERS`	number	`5`	Number of download workers
`FILTER_CHANGE_REPROCESS`	boolean	`false`	Reprocess old bundles with new filter
`BACKFILL_BUNDLE_RECORDS`	boolean	`false`	Backfill bundle records

Data Management

Variable	Type	Default	Description
`WRITE_ANS104_DATA_ITEM_DB_SIGNATURES`	boolean	`false`	Write data item signatures to DB
`WRITE_TRANSACTION_DB_SIGNATURES`	boolean	`false`	Write transaction signatures to DB
`ENABLE_DATA_DB_WAL_CLEANUP`	boolean	`false`	Enable data DB WAL cleanup
`MAX_DATA_ITEM_QUEUE_SIZE`	number	`100000`	Max data items in queue
`BUNDLE_DATA_IMPORTER_QUEUE_SIZE`	number	`1000`	Max bundles in import queue
`VERIFICATION_DATA_IMPORTER_QUEUE_SIZE`	number	`1000`	Max verification items in queue
`DATA_ITEM_FLUSH_COUNT_THRESHOLD`	number	`1000`	Data items threshold for flushing
`MAX_FLUSH_INTERVAL_SECONDS`	number	`600`	Max interval between flushes

File System Cleanup

Variable	Type	Default	Description
`FS_CLEANUP_WORKER_BATCH_SIZE`	number	`2000`	Files per cleanup batch
`FS_CLEANUP_WORKER_BATCH_PAUSE_DURATION`	number	`5000`	Pause between cleanup batches (ms)
`FS_CLEANUP_WORKER_RESTART_PAUSE_DURATION`	number	`14400000`	Pause before restarting cleanup (ms)

Background Verification

Variable	Type	Default	Description
`ENABLE_BACKGROUND_DATA_VERIFICATION`	boolean	`false`	Enable background data verification
`BACKGROUND_DATA_VERIFICATION_INTERVAL_SECONDS`	number	`600`	Verification interval
`BACKGROUND_DATA_VERIFICATION_WORKER_COUNT`	number	`1`	Number of verification workers
`BACKGROUND_DATA_VERIFICATION_STREAM_TIMEOUT_MS`	number	`30000`	Stream timeout for verification

Bundle Repair

Variable	Type	Default	Description
`BUNDLE_REPAIR_RETRY_INTERVAL_SECONDS`	number	`300`	Bundle repair retry interval
`BUNDLE_REPAIR_UPDATE_TIMESTAMPS_INTERVAL_SECONDS`	number	`300`	Timestamp update interval
`BUNDLE_REPAIR_BACKFILL_INTERVAL_SECONDS`	number	`900`	Backfill interval
`BUNDLE_REPAIR_FILTER_REPROCESS_INTERVAL_SECONDS`	number	`300`	Filter reprocess interval
`BUNDLE_REPAIR_RETRY_BATCH_SIZE`	number	`5000`	Batch size for repair retries

ArNS Configuration

Variable	Type	Default	Description
`ARNS_ROOT_HOST`	string	-	Root hostname for ArNS
`SANDBOX_PROTOCOL`	string	-	Protocol for sandboxing redirects (http or https)
`AR_IO_SDK_LOG_LEVEL`	string	`none`	ar.io SDK log level
`ARNS_CACHE_TYPE`	string	`node`	ArNS cache type
`ARNS_CACHE_TTL_SECONDS`	number	`86400`	ArNS cache TTL
`ARNS_CACHE_MAX_KEYS`	number	`10000`	Max ArNS cache keys
`ARNS_RESOLVER_PRIORITY_ORDER`	string	`gateway,on-demand`	ArNS resolver priority
`ARNS_COMPOSITE_RESOLVER_TIMEOUT_MS`	number	`3000`	Composite resolver timeout
`ARNS_NAMES_CACHE_TTL_SECONDS`	number	`3600`	Names cache TTL
`ARNS_MAX_CONCURRENT_RESOLUTIONS`	number	`1`	Max concurrent resolutions

ar.io

The gateway talks to four Solana programs that together implement the ar.io protocol (see protocol architecture). Each program ID is configured independently, so the same image can run against mainnet, staging-devnet, or a local devnet. Canonical mainnet IDs are listed in the Token docs. To confirm which set a running gateway is using, GET /ar-io/info returns the resolved programIds object.

Variable	Type	Default	Description
`AR_IO_WALLET`	string	-	Operator Solana public key (base58). Display label surfaced on `/ar-io/info`
`SOLANA_RPC_URL`	string	`https://api.mainnet-beta.solana.com`	Solana JSON-RPC endpoint. Public defaults throttle hard — use a premium provider (QuickNode, Helius, Triton) in production
`SOLANA_KEYPAIR_PATH`	string	-	Path to the operator's 64-byte Solana keypair JSON file. Signs `join_network`, `update_gateway_settings`, and cranker instructions. Inside the container the path must start with `/app/wallets/`
`SOLANA_PRIVATE_KEY`	string	-	Alternative to `SOLANA_KEYPAIR_PATH`: base58-encoded 64-byte secret (Phantom export format). Mutually exclusive with the file form
`ENABLE_EPOCH_CRANKING`	boolean	unset (= off)	When `true`, the observer runs permissionless epoch instructions (`close_observation`, `tick_epoch`, etc.). "When unset, observer skips cranking." Set `false` to make the off-state explicit
`ARIO_CORE_PROGRAM_ID`	string	-	`ario-core` program ID (token, staking, epoch state)
`ARIO_GAR_PROGRAM_ID`	string	-	`ario-gar` program ID (Gateway Registry; joins, observations, distributions)
`ARIO_ARNS_PROGRAM_ID`	string	-	`ario-arns` program ID (ArNS name registry)
`ARIO_ANT_PROGRAM_ID`	string	-	`ario-ant` program ID (ANT records — Metaplex Core NFTs that route names to data)
`AR_IO_NODE_RELEASE`	string	`33`	ar.io node release version
`APEX_TX_ID`	string	-	Apex transaction ID
`APEX_ARNS_NAME`	string	-	Apex ArNS name
`ARNS_NOT_FOUND_TX_ID`	string	-	Not found transaction ID
`ARNS_NOT_FOUND_ARNS_NAME`	string	`unregistered_arns`	Not found ArNS name

Apex Domain

Variable	Type	Default	Description
`APEX_TX_ID`	string	-	Apex transaction ID
`APEX_ARNS_NAME`	string	-	Apex ArNS name

Caching

Variable	Type	Default	Description
`CHAIN_CACHE_TYPE`	string	`lmdb`	Chain cache type (lmdb, fs, redis)
`REDIS_CACHE_URL`	string	`redis://localhost:6379`	Redis cache URL
`REDIS_USE_TLS`	boolean	`false`	Use TLS for Redis
`REDIS_CACHE_TTL_SECONDS`	number	`28800`	Redis cache TTL
`ENABLE_FS_HEADER_CACHE_CLEANUP`	boolean	`false`	Enable FS header cache cleanup
`CONTIGUOUS_DATA_CACHE_CLEANUP_THRESHOLD`	string	-	Contiguous data cache cleanup threshold

Webhooks

Variable	Type	Default	Description
`WEBHOOK_TARGET_SERVERS`	string	-	Comma-separated webhook target servers
`WEBHOOK_INDEX_FILTER`	JSON	`{"never": true}`	Webhook index filter
`WEBHOOK_BLOCK_FILTER`	JSON	`{"never": true}`	Webhook block filter

Mempool Watcher

Variable	Type	Default	Description
`ENABLE_MEMPOOL_WATCHER`	boolean	`false`	Enable mempool watcher
`MEMPOOL_POLLING_INTERVAL_MS`	number	`30000`	Mempool polling interval

AWS S3

Variable	Type	Default	Description
`AWS_ACCESS_KEY_ID`	string	-	AWS access key ID
`AWS_SECRET_ACCESS_KEY`	string	-	AWS secret access key
`AWS_SESSION_TOKEN`	string	-	AWS session token
`AWS_REGION`	string	-	AWS region
`AWS_ENDPOINT`	string	-	AWS endpoint
`AWS_S3_CONTIGUOUS_DATA_BUCKET`	string	-	S3 bucket for contiguous data
`AWS_S3_CONTIGUOUS_DATA_PREFIX`	string	-	S3 prefix for contiguous data

ClickHouse

Variable	Type	Default	Description
`CLICKHOUSE_URL`	string	-	ClickHouse URL
`CLICKHOUSE_USER`	string	-	ClickHouse username
`CLICKHOUSE_PASSWORD`	string	-	ClickHouse password

PostgreSQL (Legacy)

Variable	Type	Default	Description
`LEGACY_PSQL_CONNECTION_STRING`	string	-	PostgreSQL connection string
`LEGACY_PSQL_PASSWORD_FILE`	string	-	Path to PostgreSQL password file
`LEGACY_PSQL_SSL_REJECT_UNAUTHORIZED`	boolean	`true`	Reject unauthorized SSL connections

Solana

Variable	Type	Default	Description
`SOLANA_RPC_URL`	string	`https://api.mainnet-beta.solana.com`	Solana RPC endpoint

The default public Solana RPC is rate-limited and may block getProgramAccounts queries needed for full registry enumeration. For production gateways, use a dedicated RPC provider such as Helius, Triton, or QuickNode.

Circuit Breaker

Variable	Type	Default	Description
`ARIO_PROCESS_DEFAULT_CIRCUIT_BREAKER_TIMEOUT_MS`	number	`60000`	Circuit breaker timeout
`ARIO_PROCESS_DEFAULT_CIRCUIT_BREAKER_ERROR_THRESHOLD_PERCENTAGE`	number	`30`	Error threshold percentage
`ARIO_PROCESS_DEFAULT_CIRCUIT_BREAKER_ROLLING_COUNT_TIMEOUT_MS`	number	`600000`	Rolling count timeout
`ARIO_PROCESS_DEFAULT_CIRCUIT_BREAKER_RESET_TIMEOUT_MS`	number	`1200000`	Reset timeout

Performance Tuning

Variable	Type	Default	Description
`NODE_JS_MAX_OLD_SPACE_SIZE`	string	-	Node.js max old space size
`WEIGHTED_PEERS_TEMPERATURE_DELTA`	number	`2`	Weighted peers temperature delta
`GATEWAY_PEERS_WEIGHTS_CACHE_DURATION_MS`	number	`5000`	Gateway peers weights cache duration
`GATEWAY_PEERS_REQUEST_WINDOW_COUNT`	number	`20`	Gateway peers request window count
`TAG_SELECTIVITY`	JSON	`{"Parent-Folder-Id": 20, "Message": 20, "Drive-Id": 10, "Process": 10, "Recipient": 10, "App-Name": -10, "Content-Type": -10, "Data-Protocol": -10}`	Tag selectivity configuration

Data Paths

Variable	Type	Default	Description
`CHUNKS_DATA_PATH`	string	`./data/chunks`	Path to chunks data
`CONTIGUOUS_DATA_PATH`	string	`./data/contiguous`	Path to contiguous data
`HEADERS_DATA_PATH`	string	`./data/headers`	Path to headers data
`SQLITE_DATA_PATH`	string	`./data/sqlite`	Path to SQLite data
`DUCKDB_DATA_PATH`	string	`./data/duckdb`	Path to DuckDB data
`TEMP_DATA_PATH`	string	`./data/tmp`	Path to temporary data
`LMDB_DATA_PATH`	string	`./data/lmdb`	Path to LMDB data
`PARQUET_DATA_PATH`	string	`./data/parquet`	Path to Parquet data

Rate Limiter

Variable	Type	Default	Description
`ENABLE_RATE_LIMITER`	boolean	`false`	Enable rate limiting system
`RATE_LIMITER_TYPE`	string	`memory`	Rate limiter type (memory or redis)
`RATE_LIMITER_REDIS_ENDPOINT`	string	-	Redis endpoint for rate limiter
`RATE_LIMITER_IP_TOKENS_PER_BUCKET`	number	`100000`	IP bucket token capacity
`RATE_LIMITER_IP_REFILL_PER_SEC`	number	`20`	IP bucket refill rate per second
`RATE_LIMITER_RESOURCE_TOKENS_PER_BUCKET`	number	`1000000`	Resource bucket token capacity
`RATE_LIMITER_RESOURCE_REFILL_PER_SEC`	number	`100`	Resource bucket refill rate
`RATE_LIMITER_IPS_AND_CIDRS_ALLOWLIST`	string	-	Comma-separated IP/CIDR allowlist
`RATE_LIMITER_ARNS_ALLOWLIST`	string	-	Comma-separated ArNS allowlist

x402 Payment Protocol

Variable	Type	Default	Description
`ENABLE_X_402_USDC_DATA_EGRESS`	boolean	`false`	Enable x402 USDC payments
`X_402_USDC_NETWORK`	string	-	Base network (base-sepolia or base)
`X_402_USDC_WALLET_ADDRESS`	string	-	USDC wallet address for receiving payments
`X_402_USDC_FACILITATOR_URL`	string	-	Payment facilitator URL
`X_402_USDC_PER_BYTE_PRICE`	number	`0.0000000001`	Price per byte in USDC
`X_402_USDC_DATA_EGRESS_MIN_PRICE`	number	`0.001`	Minimum payment amount
`X_402_USDC_DATA_EGRESS_MAX_PRICE`	number	`1.00`	Maximum payment amount
`X_402_RATE_LIMIT_CAPACITY_MULTIPLIER`	number	`10`	Paid token capacity multiplier
`X_402_APP_NAME`	string	-	Application name for paywall
`X_402_APP_LOGO`	string	-	Application logo URL for paywall
`X_402_CDP_CLIENT_KEY`	string	-	PUBLIC: CDP client key for Onramp (optional testnet, required mainnet)
`CDP_API_KEY_ID`	string	-	SECRET: CDP API key ID for Onramp (optional testnet, required mainnet)
`CDP_API_KEY_SECRET`	string	-	SECRET: CDP API secret for Onramp (use CDP_API_KEY_SECRET_FILE instead)
`CDP_API_KEY_SECRET_FILE`	string	-	SECRET: Path to CDP secret file for Onramp (takes precedence, recommended)
`CHUNK_GET_BASE64_SIZE_BYTES`	number	`368640`	Fixed size for chunk pricing

Observer Service

Basic Configuration

Variable	Type	Default	Description
`PORT`	number	`5050`	Observer service port
`LOG_LEVEL`	string	-	Observer log level
`OBSERVER_WALLET`	string	-	Observer wallet
`IO_PROCESS_ID`	string	-	ar.io Solana program address
`AR_IO_NODE_RELEASE`	string	`33`	ar.io node release version

Observer Operation

Variable	Type	Default	Description
`SUBMIT_CONTRACT_INTERACTIONS`	boolean	`true`	Submit observations to Solana programs
`NUM_ARNS_NAMES_TO_OBSERVE_PER_GROUP`	number	`8`	Number of ArNS names per observation group
`REPORT_GENERATION_INTERVAL_MS`	string	-	Report generation interval
`REPORT_DATA_SINK`	string	-	Report data sink
`TURBO_UPLOAD_SERVICE_URL`	string	-	Turbo upload service URL
`RUN_OBSERVER`	boolean	`true`	Run observer service
`MIN_RELEASE_NUMBER`	number	`0`	Minimum release number

Report Configuration

Variable	Type	Default	Description
`REPORT_GENERATION_INTERVAL_MS`	string	-	Report generation interval
`REPORT_DATA_SINK`	string	-	Report data sink

Gateway Assessment

Variable	Type	Default	Description
`NUM_ARNS_NAMES_TO_OBSERVE_PER_GROUP`	number	`8`	Number of ArNS names per observation group

ArNS Names

Variable	Type	Default	Description
`NUM_ARNS_NAMES_TO_OBSERVE_PER_GROUP`	number	`8`	Number of ArNS names per observation group

On-Chain Observations

Variable	Type	Default	Description
`SUBMIT_CONTRACT_INTERACTIONS`	boolean	`true`	Submit observations to Solana programs. Pre-flight no-ops unless your pubkey is in `epoch.prescribed_observers` — harmless to leave at default before `join_network`

Upload Wallet Identities

The observer uploads report bundles to Turbo. The upload signer is resolved from the first matching env in the precedence chain. Setting envs from more than one chain group at once is rejected at startup.

Variable	Type	Default	Description
`ARWEAVE_UPLOAD_KEY_FILE`	string	-	Path to an Arweave JWK file. Highest priority for upload signing
`ARWEAVE_UPLOAD_JWK`	string	-	Inline Arweave JWK JSON. Lower priority than the file form
`ETHEREUM_UPLOAD_PRIVATE_KEY_FILE`	string	-	Path to a 32-byte hex private key (with or without `0x` prefix)
`ETHEREUM_UPLOAD_PRIVATE_KEY`	string	-	Inline hex private key. Lower priority than the file form
`SOLANA_UPLOAD_KEYPAIR_PATH`	string	-	Path to a separate Solana keypair JSON for uploads. Ignored when any `ARWEAVE_UPLOAD_` or `ETHEREUM_UPLOAD_` is set
`SOLANA_UPLOAD_PRIVATE_KEY`	string	-	Alternative to above: base58 secret. Mutually exclusive with the file form

When none of the above are set, uploads fall back to the observer key, then the operator key.

Offset Observation

Variable	Type	Default	Description
`REPORT_GENERATION_INTERVAL_MS`	string	-	Report generation interval

Data Paths

Variable	Type	Default	Description
`TEMP_DATA_PATH`	string	`./data/tmp`	Path to temporary data
`REPORTS_DATA_PATH`	string	`./data/reports`	Path to reports data
`WALLETS_PATH`	string	`./wallets`	Path to wallets

Envoy Proxy

Basic Configuration

Variable	Type	Default	Description
`LOG_LEVEL`	string	`info`	Envoy log level
`TVAL_AR_IO_HOST`	string	`core`	ar.io host
`TVAL_AR_IO_PORT`	number	`4000`	ar.io port
`TVAL_OBSERVER_HOST`	string	`observer`	Observer host
`TVAL_OBSERVER_PORT`	number	`5050`	Observer port
`TVAL_GATEWAY_HOST`	string	`turbo-gateway.com`	Gateway host
`TVAL_GRAPHQL_HOST`	string	`core`	GraphQL host
`TVAL_GRAPHQL_PORT`	number	`4000`	GraphQL port
`TVAL_ARNS_ROOT_HOST`	string	-	ArNS root host

Redis Cache

Basic Configuration

Variable	Type	Default	Description
`REDIS_IMAGE_TAG`	string	`7`	Redis image tag
`REDIS_MAX_MEMORY`	string	`256mb`	Redis max memory
`EXTRA_REDIS_FLAGS`	string	`--save "" --appendonly no`	Extra Redis flags

Data Paths

Variable	Type	Default	Description
`REDIS_DATA_PATH`	string	`./data/redis`	Path to Redis data

ClickHouse

Basic Configuration

Variable	Type	Default	Description
`CLICKHOUSE_IMAGE_TAG`	string	`25.4`	ClickHouse image tag
`CLICKHOUSE_USER`	string	-	ClickHouse username
`CLICKHOUSE_PASSWORD`	string	-	ClickHouse password

Data Paths

Variable	Type	Default	Description
`CLICKHOUSE_DATA_PATH`	string	`./data/clickhouse`	Path to ClickHouse data
`CLICKHOUSE_LOGS_PATH`	string	`./logs/clickhouse`	Path to ClickHouse logs

ClickHouse Auto-Import

Variable	Type	Default	Description
`CLICKHOUSE_AUTO_IMPORT_IMAGE_TAG`	string	`79792e1b549f64edad3e338769949fd9bffa62db`	ClickHouse auto-import image tag
`CLICKHOUSE_DEBUG`	string	-	ClickHouse debug flag
`AR_IO_HOST`	string	`core`	ar.io host
`AR_IO_PORT`	number	`4000`	ar.io port
`ADMIN_API_KEY`	string	-	Admin API key
`PARQUET_DATA_PATH`	string	`./data/parquet`	Path to Parquet data
`CLICKHOUSE_HOST`	string	`clickhouse`	ClickHouse host
`CLICKHOUSE_PORT`	string	-	ClickHouse port (defaults to 9000)
`CLICKHOUSE_USER`	string	-	ClickHouse username (defaults to 'default')
`CLICKHOUSE_PASSWORD`	string	-	ClickHouse password (required)
`CLICKHOUSE_AUTO_IMPORT_SLEEP_INTERVAL`	string	-	Auto-import sleep interval
`CLICKHOUSE_AUTO_IMPORT_HEIGHT_INTERVAL`	string	-	Auto-import height interval
`CLICKHOUSE_AUTO_IMPORT_MAX_ROWS_PER_FILE`	string	-	Max rows per file for auto-import

Litestream Backup

S3 Configuration

Variable	Type	Default	Description
`LITESTREAM_IMAGE_TAG`	string	`be121fc0ae24a9eb7cdb2b92d01f047039b5f5e8`	Litestream image tag
`AR_IO_SQLITE_BACKUP_S3_BUCKET_NAME`	string	-	S3 bucket name for SQLite backups
`AR_IO_SQLITE_BACKUP_S3_BUCKET_REGION`	string	-	S3 bucket region for SQLite backups
`AR_IO_SQLITE_BACKUP_S3_BUCKET_ACCESS_KEY`	string	-	S3 access key for SQLite backups
`AR_IO_SQLITE_BACKUP_S3_BUCKET_SECRET_KEY`	string	-	S3 secret key for SQLite backups
`AR_IO_SQLITE_BACKUP_S3_BUCKET_PREFIX`	string	-	S3 prefix for SQLite backups

Data Paths

Variable	Type	Default	Description
`SQLITE_DATA_PATH`	string	`./data/sqlite`	Path to SQLite data

Autoheal Service

Configuration

Variable	Type	Default	Description
`AUTOHEAL_CONTAINER_LABEL`	string	`autoheal`	Container label for autoheal
`AUTOHEAL_ONLY_MONITOR_RUNNING`	boolean	`false`	Only monitor running containers
`RUN_AUTOHEAL`	boolean	`false`	Enable autoheal service

OpenTelemetry Tracing

Basic Configuration

Variable	Type	Default	Description
`OTEL_SERVICE_NAME`	string	`ar-io-node`	OpenTelemetry service name
`OTEL_EXPORTER_OTLP_ENDPOINT`	string	-	OTLP exporter endpoint
`OTEL_EXPORTER_OTLP_HEADERS`	string	-	OTLP exporter headers
`OTEL_EXPORTER_OTLP_HEADERS_FILE`	string	-	Path to OTLP exporter headers file

Performance Tuning

Variable	Type	Default	Description
`OTEL_BATCH_LOG_PROCESSOR_SCHEDULED_DELAY_MS`	number	`5000`	Batch log processor scheduled delay
`OTEL_BATCH_LOG_PROCESSOR_MAX_EXPORT_BATCH_SIZE`	number	`512`	Max export batch size
`OTEL_TRACING_SAMPLING_RATE_DENOMINATOR`	number	`1000`	Tracing sampling rate denominator

Image Tags

Service Images

Variable	Type	Default	Description
`ENVOY_IMAGE_TAG`	string	`4789af164fcd3029a65a1d6739f2d9026567206e`	Envoy image tag
`CORE_IMAGE_TAG`	string	`3a793c6ee06f5e1df56920fc70184b213ceb8c6e`	Core image tag
`OBSERVER_IMAGE_TAG`	string	`e5f6ae36fd6eea04be5ebba2624f8ecc08db4ea0`	Observer image tag
`LITESTREAM_IMAGE_TAG`	string	`be121fc0ae24a9eb7cdb2b92d01f047039b5f5e8`	Litestream image tag
`CLICKHOUSE_AUTO_IMPORT_IMAGE_TAG`	string	`79792e1b549f64edad3e338769949fd9bffa62db`	ClickHouse auto-import image tag

Additional Paths

Data Directories

Variable	Type	Default	Description
`CHUNKS_DATA_PATH`	string	`./data/chunks`	Path to chunks data
`CONTIGUOUS_DATA_PATH`	string	`./data/contiguous`	Path to contiguous data
`HEADERS_DATA_PATH`	string	`./data/headers`	Path to headers data
`SQLITE_DATA_PATH`	string	`./data/sqlite`	Path to SQLite data
`DUCKDB_DATA_PATH`	string	`./data/duckdb`	Path to DuckDB data
`TEMP_DATA_PATH`	string	`./data/tmp`	Path to temporary data
`LMDB_DATA_PATH`	string	`./data/lmdb`	Path to LMDB data
`PARQUET_DATA_PATH`	string	`./data/parquet`	Path to Parquet data
`REDIS_DATA_PATH`	string	`./data/redis`	Path to Redis data
`CLICKHOUSE_DATA_PATH`	string	`./data/clickhouse`	Path to ClickHouse data
`CLICKHOUSE_LOGS_PATH`	string	`./logs/clickhouse`	Path to ClickHouse logs
`REPORTS_DATA_PATH`	string	`./data/reports`	Path to reports data
`WALLETS_PATH`	string	`./wallets`	Path to wallets

Usage Notes

All environment variables are optional unless otherwise specified
Default values are shown in the "Default" column
Boolean values should be set to true or false
JSON values should be valid JSON strings
Path values should be absolute or relative to the project root
Some variables are only used in specific deployment scenarios (e.g., ClickHouse, Litestream)
Image tags can be updated to use different versions of the services
Data paths can be customized based on your storage requirements

Configuration Examples

Basic Gateway Setup

# Core configuration
NODE_ENV=production
LOG_LEVEL=info
PORT=4000
ADMIN_API_KEY=your-admin-key-here

# Network configuration
TRUSTED_NODE_URL=https://turbo-gateway.com
TRUSTED_GATEWAY_URL=https://turbo-gateway.com

# Data paths
CHUNKS_DATA_PATH=/data/chunks
CONTIGUOUS_DATA_PATH=/data/contiguous
SQLITE_DATA_PATH=/data/sqlite

Advanced Gateway with ClickHouse

# Core configuration
NODE_ENV=production
LOG_LEVEL=info
PORT=4000
ADMIN_API_KEY=your-admin-key-here

# ClickHouse configuration
CLICKHOUSE_URL=http://clickhouse:8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password

# Bundle processing
ANS104_UNBUNDLE_FILTER={"and": [{"equals": {"App-Name": "MyApp-v1.0"}}]}
ANS104_INDEX_FILTER={"and": [{"equals": {"App-Name": "MyApp-v1.0"}}]}
ANS104_UNBUNDLE_WORKERS=2
ANS104_DOWNLOAD_WORKERS=5

Gateway with Redis Caching

# Core configuration
NODE_ENV=production
LOG_LEVEL=info
PORT=4000
ADMIN_API_KEY=your-admin-key-here

# Redis configuration
CHAIN_CACHE_TYPE=redis
REDIS_CACHE_URL=redis://redis:6379
REDIS_USE_TLS=false
REDIS_CACHE_TTL_SECONDS=28800

# ArNS configuration
ARNS_ROOT_HOST=your-domain.com
ARNS_CACHE_TYPE=redis

This comprehensive reference should help you configure your ar.io Gateway with the appropriate environment variables for your specific use case.

How is this guide?

Environment Variables

On this page