AR.IO LogoAR.IO Documentation
BuildRun a gatewayManage

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

VariableTypeDefaultDescription
PORTnumber4000HTTP server port
NODE_ENVstringproductionNode.js environment
LOG_LEVELstringinfoLogging level (error, warn, info, debug)
LOG_FORMATstringsimpleLog format (simple, json)
LOG_FILTERstring{"always":true}Log filtering configuration
LOG_ALL_STACKTRACESbooleanfalseInclude full stack traces in logs
INSTANCE_IDstring-Unique instance identifier

Authentication & Security

VariableTypeDefaultDescription
ADMIN_API_KEYStringGeneratedAPI key for admin endpoints (auto-generated if not set)
ADMIN_API_KEY_FILEString-Path to file containing admin API key

Network Configuration

VariableTypeDefaultDescription
TRUSTED_NODE_URLstringhttps://arweave.netTrusted Arweave node URL
TRUSTED_GATEWAY_URLstringhttps://arweave.netPrimary trusted gateway URL
TRUSTED_GATEWAYS_URLSJSON{"https://arweave.net": 1}Weighted trusted gateway URLs
TRUSTED_GATEWAYS_REQUEST_TIMEOUT_MSnumber10000Request timeout for trusted gateways
ARWEAVE_NODE_IGNORE_URLSstring-Comma-separated URLs to ignore

Chunk Management

VariableTypeDefaultDescription
CHUNK_POST_URLSstringhttps://arweave.net/chunkURLs for posting chunks
CHUNK_POST_CONCURRENCY_LIMITnumber2Max concurrent chunk posts
CHUNK_POST_MIN_SUCCESS_COUNTnumber3Min successful chunk posts required
CHUNK_POST_RESPONSE_TIMEOUT_MSnumber-Chunk POST response timeout
CHUNK_POST_ABORT_TIMEOUT_MSnumber-Chunk POST abort timeout
SECONDARY_CHUNK_POST_URLSstring-Secondary chunk POST URLs
SECONDARY_CHUNK_POST_CONCURRENCY_LIMITnumber2Secondary chunk POST concurrency
SECONDARY_CHUNK_POST_MIN_SUCCESS_COUNTnumber1Secondary chunk POST success count

Data Sources

VariableTypeDefaultDescription
ON_DEMAND_RETRIEVAL_ORDERstrings3,trusted-gateways,chunks,tx-dataOn-demand data retrieval priority
BACKGROUND_RETRIEVAL_ORDERstringchunks,s3,trusted-gateways,tx-dataBackground data retrieval priority
CHUNK_DATA_SOURCE_TYPEstringfsChunk data source type (fs, legacy-s3)
CHUNK_METADATA_SOURCE_TYPEstringfsChunk metadata source type (fs, legacy-psql)

Indexing & Synchronization

VariableTypeDefaultDescription
START_WRITERSbooleantrueEnable indexing processes
START_HEIGHTnumber0Starting block height for indexing
STOP_HEIGHTnumberInfinityStopping block height for indexing
SKIP_CACHEbooleanfalseBypass header cache
SIMULATED_REQUEST_FAILURE_RATEnumber0Rate of simulated request failures

ANS-104 Bundle Processing

VariableTypeDefaultDescription
ANS104_UNBUNDLE_FILTERJSON{"never": true}Filter for bundles to unbundle
ANS104_INDEX_FILTERJSON{"never": true}Filter for data items to index
ANS104_UNBUNDLE_WORKERSnumber1Number of unbundling workers
ANS104_DOWNLOAD_WORKERSnumber5Number of download workers
FILTER_CHANGE_REPROCESSbooleanfalseReprocess old bundles with new filter
BACKFILL_BUNDLE_RECORDSbooleanfalseBackfill bundle records

Data Management

VariableTypeDefaultDescription
WRITE_ANS104_DATA_ITEM_DB_SIGNATURESbooleanfalseWrite data item signatures to DB
WRITE_TRANSACTION_DB_SIGNATURESbooleanfalseWrite transaction signatures to DB
ENABLE_DATA_DB_WAL_CLEANUPbooleanfalseEnable data DB WAL cleanup
MAX_DATA_ITEM_QUEUE_SIZEnumber100000Max data items in queue
BUNDLE_DATA_IMPORTER_QUEUE_SIZEnumber1000Max bundles in import queue
VERIFICATION_DATA_IMPORTER_QUEUE_SIZEnumber1000Max verification items in queue
DATA_ITEM_FLUSH_COUNT_THRESHOLDnumber1000Data items threshold for flushing
MAX_FLUSH_INTERVAL_SECONDSnumber600Max interval between flushes

File System Cleanup

VariableTypeDefaultDescription
FS_CLEANUP_WORKER_BATCH_SIZEnumber2000Files per cleanup batch
FS_CLEANUP_WORKER_BATCH_PAUSE_DURATIONnumber5000Pause between cleanup batches (ms)
FS_CLEANUP_WORKER_RESTART_PAUSE_DURATIONnumber14400000Pause before restarting cleanup (ms)

Background Verification

VariableTypeDefaultDescription
ENABLE_BACKGROUND_DATA_VERIFICATIONbooleanfalseEnable background data verification
BACKGROUND_DATA_VERIFICATION_INTERVAL_SECONDSnumber600Verification interval
BACKGROUND_DATA_VERIFICATION_WORKER_COUNTnumber1Number of verification workers
BACKGROUND_DATA_VERIFICATION_STREAM_TIMEOUT_MSnumber30000Stream timeout for verification

Bundle Repair

VariableTypeDefaultDescription
BUNDLE_REPAIR_RETRY_INTERVAL_SECONDSnumber300Bundle repair retry interval
BUNDLE_REPAIR_UPDATE_TIMESTAMPS_INTERVAL_SECONDSnumber300Timestamp update interval
BUNDLE_REPAIR_BACKFILL_INTERVAL_SECONDSnumber900Backfill interval
BUNDLE_REPAIR_FILTER_REPROCESS_INTERVAL_SECONDSnumber300Filter reprocess interval
BUNDLE_REPAIR_RETRY_BATCH_SIZEnumber5000Batch size for repair retries

ArNS Configuration

VariableTypeDefaultDescription
ARNS_ROOT_HOSTstring-Root hostname for ArNS
SANDBOX_PROTOCOLstring-Protocol for sandboxing redirects (http or https)
AR_IO_SDK_LOG_LEVELstringnoneAR.IO SDK log level
ARNS_CACHE_TYPEstringnodeArNS cache type
ARNS_CACHE_TTL_SECONDSnumber86400ArNS cache TTL
ARNS_CACHE_MAX_KEYSnumber10000Max ArNS cache keys
ARNS_RESOLVER_PRIORITY_ORDERstringgateway,on-demandArNS resolver priority
ARNS_COMPOSITE_RESOLVER_TIMEOUT_MSnumber3000Composite resolver timeout
ARNS_NAMES_CACHE_TTL_SECONDSnumber3600Names cache TTL
ARNS_MAX_CONCURRENT_RESOLUTIONSnumber1Max concurrent resolutions

AR.IO Network

VariableTypeDefaultDescription
AR_IO_WALLETstring-Gateway wallet
IO_PROCESS_IDstringqNvAoz0TgcH7DMg8BCVn8jF32QH5L6T29VjHxhHqqGEAR.IO process ID
AR_IO_NODE_RELEASEstring33AR.IO node release version
APEX_TX_IDstring-Apex transaction ID
APEX_ARNS_NAMEstring-Apex ArNS name
ARNS_NOT_FOUND_TX_IDstring-Not found transaction ID
ARNS_NOT_FOUND_ARNS_NAMEstringunregistered_arnsNot found ArNS name

Apex Domain

VariableTypeDefaultDescription
APEX_TX_IDstring-Apex transaction ID
APEX_ARNS_NAMEstring-Apex ArNS name

Caching

VariableTypeDefaultDescription
CHAIN_CACHE_TYPEstringlmdbChain cache type (lmdb, fs, redis)
REDIS_CACHE_URLstringredis://localhost:6379Redis cache URL
REDIS_USE_TLSbooleanfalseUse TLS for Redis
REDIS_CACHE_TTL_SECONDSnumber28800Redis cache TTL
ENABLE_FS_HEADER_CACHE_CLEANUPbooleanfalseEnable FS header cache cleanup
CONTIGUOUS_DATA_CACHE_CLEANUP_THRESHOLDstring-Contiguous data cache cleanup threshold

Webhooks

VariableTypeDefaultDescription
WEBHOOK_TARGET_SERVERSstring-Comma-separated webhook target servers
WEBHOOK_INDEX_FILTERJSON{"never": true}Webhook index filter
WEBHOOK_BLOCK_FILTERJSON{"never": true}Webhook block filter

Mempool Watcher

VariableTypeDefaultDescription
ENABLE_MEMPOOL_WATCHERbooleanfalseEnable mempool watcher
MEMPOOL_POLLING_INTERVAL_MSnumber30000Mempool polling interval

AWS S3

VariableTypeDefaultDescription
AWS_ACCESS_KEY_IDstring-AWS access key ID
AWS_SECRET_ACCESS_KEYstring-AWS secret access key
AWS_SESSION_TOKENstring-AWS session token
AWS_REGIONstring-AWS region
AWS_ENDPOINTstring-AWS endpoint
AWS_S3_CONTIGUOUS_DATA_BUCKETstring-S3 bucket for contiguous data
AWS_S3_CONTIGUOUS_DATA_PREFIXstring-S3 prefix for contiguous data

ClickHouse

VariableTypeDefaultDescription
CLICKHOUSE_URLstring-ClickHouse URL
CLICKHOUSE_USERstring-ClickHouse username
CLICKHOUSE_PASSWORDstring-ClickHouse password

PostgreSQL (Legacy)

VariableTypeDefaultDescription
LEGACY_PSQL_CONNECTION_STRINGstring-PostgreSQL connection string
LEGACY_PSQL_PASSWORD_FILEstring-Path to PostgreSQL password file
LEGACY_PSQL_SSL_REJECT_UNAUTHORIZEDbooleantrueReject unauthorized SSL connections

AO (Autonomous Objects)

VariableTypeDefaultDescription
AO_CU_URLstring-AO CU URL
NETWORK_AO_CU_URLstring-Network AO CU URL
ANT_AO_CU_URLstring-ANT AO CU URL
AO_MU_URLstring-AO MU URL
AO_GATEWAY_URLstring-AO Gateway URL
AO_GRAPHQL_URLstring-AO GraphQL URL

Circuit Breaker

VariableTypeDefaultDescription
ARIO_PROCESS_DEFAULT_CIRCUIT_BREAKER_TIMEOUT_MSnumber60000Circuit breaker timeout
ARIO_PROCESS_DEFAULT_CIRCUIT_BREAKER_ERROR_THRESHOLD_PERCENTAGEnumber30Error threshold percentage
ARIO_PROCESS_DEFAULT_CIRCUIT_BREAKER_ROLLING_COUNT_TIMEOUT_MSnumber600000Rolling count timeout
ARIO_PROCESS_DEFAULT_CIRCUIT_BREAKER_RESET_TIMEOUT_MSnumber1200000Reset timeout

Performance Tuning

VariableTypeDefaultDescription
NODE_JS_MAX_OLD_SPACE_SIZEstring-Node.js max old space size
WEIGHTED_PEERS_TEMPERATURE_DELTAnumber2Weighted peers temperature delta
GATEWAY_PEERS_WEIGHTS_CACHE_DURATION_MSnumber5000Gateway peers weights cache duration
GATEWAY_PEERS_REQUEST_WINDOW_COUNTnumber20Gateway peers request window count
TAG_SELECTIVITYJSON{"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

VariableTypeDefaultDescription
CHUNKS_DATA_PATHstring./data/chunksPath to chunks data
CONTIGUOUS_DATA_PATHstring./data/contiguousPath to contiguous data
HEADERS_DATA_PATHstring./data/headersPath to headers data
SQLITE_DATA_PATHstring./data/sqlitePath to SQLite data
DUCKDB_DATA_PATHstring./data/duckdbPath to DuckDB data
TEMP_DATA_PATHstring./data/tmpPath to temporary data
LMDB_DATA_PATHstring./data/lmdbPath to LMDB data
PARQUET_DATA_PATHstring./data/parquetPath to Parquet data

Observer Service

Basic Configuration

VariableTypeDefaultDescription
PORTnumber5050Observer service port
LOG_LEVELstring-Observer log level
OBSERVER_WALLETstring-Observer wallet
IO_PROCESS_IDstring-AR.IO process ID
AR_IO_NODE_RELEASEstring33AR.IO node release version

Observer Operation

VariableTypeDefaultDescription
SUBMIT_CONTRACT_INTERACTIONSbooleantrueSubmit contract interactions
NUM_ARNS_NAMES_TO_OBSERVE_PER_GROUPnumber8Number of ArNS names per observation group
REPORT_GENERATION_INTERVAL_MSstring-Report generation interval
REPORT_DATA_SINKstring-Report data sink
TURBO_UPLOAD_SERVICE_URLstring-Turbo upload service URL
RUN_OBSERVERbooleantrueRun observer service
MIN_RELEASE_NUMBERnumber0Minimum release number

Report Configuration

VariableTypeDefaultDescription
REPORT_GENERATION_INTERVAL_MSstring-Report generation interval
REPORT_DATA_SINKstring-Report data sink

Gateway Assessment

VariableTypeDefaultDescription
NUM_ARNS_NAMES_TO_OBSERVE_PER_GROUPnumber8Number of ArNS names per observation group

ArNS Names

VariableTypeDefaultDescription
NUM_ARNS_NAMES_TO_OBSERVE_PER_GROUPnumber8Number of ArNS names per observation group

Contract Interaction

VariableTypeDefaultDescription
SUBMIT_CONTRACT_INTERACTIONSbooleantrueSubmit contract interactions

Offset Observation

VariableTypeDefaultDescription
REPORT_GENERATION_INTERVAL_MSstring-Report generation interval

AO (Autonomous Objects)

VariableTypeDefaultDescription
AO_CU_URLstring-AO CU URL
NETWORK_AO_CU_URLstring-Network AO CU URL
AO_MU_URLstring-AO MU URL
AO_GATEWAY_URLstring-AO Gateway URL
AO_GRAPHQL_URLstring-AO GraphQL URL

Data Paths

VariableTypeDefaultDescription
TEMP_DATA_PATHstring./data/tmpPath to temporary data
REPORTS_DATA_PATHstring./data/reportsPath to reports data
WALLETS_PATHstring./walletsPath to wallets

Envoy Proxy

Basic Configuration

VariableTypeDefaultDescription
LOG_LEVELstringinfoEnvoy log level
TVAL_AR_IO_HOSTstringcoreAR.IO host
TVAL_AR_IO_PORTnumber4000AR.IO port
TVAL_OBSERVER_HOSTstringobserverObserver host
TVAL_OBSERVER_PORTnumber5050Observer port
TVAL_GATEWAY_HOSTstringarweave.netGateway host
TVAL_GRAPHQL_HOSTstringcoreGraphQL host
TVAL_GRAPHQL_PORTnumber4000GraphQL port
TVAL_ARNS_ROOT_HOSTstring-ArNS root host

Redis Cache

Basic Configuration

VariableTypeDefaultDescription
REDIS_IMAGE_TAGstring7Redis image tag
REDIS_MAX_MEMORYstring256mbRedis max memory
EXTRA_REDIS_FLAGSstring--save "" --appendonly noExtra Redis flags

Data Paths

VariableTypeDefaultDescription
REDIS_DATA_PATHstring./data/redisPath to Redis data

ClickHouse

Basic Configuration

VariableTypeDefaultDescription
CLICKHOUSE_IMAGE_TAGstring25.4ClickHouse image tag
CLICKHOUSE_USERstring-ClickHouse username
CLICKHOUSE_PASSWORDstring-ClickHouse password

Data Paths

VariableTypeDefaultDescription
CLICKHOUSE_DATA_PATHstring./data/clickhousePath to ClickHouse data
CLICKHOUSE_LOGS_PATHstring./logs/clickhousePath to ClickHouse logs

ClickHouse Auto-Import

VariableTypeDefaultDescription
CLICKHOUSE_AUTO_IMPORT_IMAGE_TAGstring79792e1b549f64edad3e338769949fd9bffa62dbClickHouse auto-import image tag
CLICKHOUSE_DEBUGstring-ClickHouse debug flag
AR_IO_HOSTstringcoreAR.IO host
AR_IO_PORTnumber4000AR.IO port
ADMIN_API_KEYstring-Admin API key
PARQUET_DATA_PATHstring./data/parquetPath to Parquet data
CLICKHOUSE_HOSTstringclickhouseClickHouse host
CLICKHOUSE_PORTstring-ClickHouse port (defaults to 9000)
CLICKHOUSE_USERstring-ClickHouse username (defaults to 'default')
CLICKHOUSE_PASSWORDstring-ClickHouse password (required)
CLICKHOUSE_AUTO_IMPORT_SLEEP_INTERVALstring-Auto-import sleep interval
CLICKHOUSE_AUTO_IMPORT_HEIGHT_INTERVALstring-Auto-import height interval
CLICKHOUSE_AUTO_IMPORT_MAX_ROWS_PER_FILEstring-Max rows per file for auto-import

Litestream Backup

S3 Configuration

VariableTypeDefaultDescription
LITESTREAM_IMAGE_TAGstringbe121fc0ae24a9eb7cdb2b92d01f047039b5f5e8Litestream image tag
AR_IO_SQLITE_BACKUP_S3_BUCKET_NAMEstring-S3 bucket name for SQLite backups
AR_IO_SQLITE_BACKUP_S3_BUCKET_REGIONstring-S3 bucket region for SQLite backups
AR_IO_SQLITE_BACKUP_S3_BUCKET_ACCESS_KEYstring-S3 access key for SQLite backups
AR_IO_SQLITE_BACKUP_S3_BUCKET_SECRET_KEYstring-S3 secret key for SQLite backups
AR_IO_SQLITE_BACKUP_S3_BUCKET_PREFIXstring-S3 prefix for SQLite backups

Data Paths

VariableTypeDefaultDescription
SQLITE_DATA_PATHstring./data/sqlitePath to SQLite data

Autoheal Service

Configuration

VariableTypeDefaultDescription
AUTOHEAL_CONTAINER_LABELstringautohealContainer label for autoheal
AUTOHEAL_ONLY_MONITOR_RUNNINGbooleanfalseOnly monitor running containers
RUN_AUTOHEALbooleanfalseEnable autoheal service

OpenTelemetry Tracing

Basic Configuration

VariableTypeDefaultDescription
OTEL_SERVICE_NAMEstringar-io-nodeOpenTelemetry service name
OTEL_EXPORTER_OTLP_ENDPOINTstring-OTLP exporter endpoint
OTEL_EXPORTER_OTLP_HEADERSstring-OTLP exporter headers
OTEL_EXPORTER_OTLP_HEADERS_FILEstring-Path to OTLP exporter headers file

Performance Tuning

VariableTypeDefaultDescription
OTEL_BATCH_LOG_PROCESSOR_SCHEDULED_DELAY_MSnumber5000Batch log processor scheduled delay
OTEL_BATCH_LOG_PROCESSOR_MAX_EXPORT_BATCH_SIZEnumber512Max export batch size
OTEL_TRACING_SAMPLING_RATE_DENOMINATORnumber1000Tracing sampling rate denominator

Image Tags

Service Images

VariableTypeDefaultDescription
ENVOY_IMAGE_TAGstring4789af164fcd3029a65a1d6739f2d9026567206eEnvoy image tag
CORE_IMAGE_TAGstring3a793c6ee06f5e1df56920fc70184b213ceb8c6eCore image tag
OBSERVER_IMAGE_TAGstringe5f6ae36fd6eea04be5ebba2624f8ecc08db4ea0Observer image tag
LITESTREAM_IMAGE_TAGstringbe121fc0ae24a9eb7cdb2b92d01f047039b5f5e8Litestream image tag
CLICKHOUSE_AUTO_IMPORT_IMAGE_TAGstring79792e1b549f64edad3e338769949fd9bffa62dbClickHouse auto-import image tag

Additional Paths

Data Directories

VariableTypeDefaultDescription
CHUNKS_DATA_PATHstring./data/chunksPath to chunks data
CONTIGUOUS_DATA_PATHstring./data/contiguousPath to contiguous data
HEADERS_DATA_PATHstring./data/headersPath to headers data
SQLITE_DATA_PATHstring./data/sqlitePath to SQLite data
DUCKDB_DATA_PATHstring./data/duckdbPath to DuckDB data
TEMP_DATA_PATHstring./data/tmpPath to temporary data
LMDB_DATA_PATHstring./data/lmdbPath to LMDB data
PARQUET_DATA_PATHstring./data/parquetPath to Parquet data
REDIS_DATA_PATHstring./data/redisPath to Redis data
CLICKHOUSE_DATA_PATHstring./data/clickhousePath to ClickHouse data
CLICKHOUSE_LOGS_PATHstring./logs/clickhousePath to ClickHouse logs
REPORTS_DATA_PATHstring./data/reportsPath to reports data
WALLETS_PATHstring./walletsPath 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://arweave.net
TRUSTED_GATEWAY_URL=https://arweave.net

# 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?