Environmental Variables
Overview
The AR.IO Gateway allows configuration customization through environmental variables. These variables dictate the gateway's behavior, from block synchronization settings to log formatting. Detailed below is a table enumerating all available environmental variables, their respective types, default values, and a brief description. Note that certain variables, such as SANDBOX_PROTOCOL, rely on others (e.g., ARNS_ROOT_HOST) to function effectively. Ensure proper understanding of these dependencies when configuring.
Variables
| ENV Name | Type | Default Value | Description |
|---|---|---|---|
| GRAPHQL_HOST | String | arweave.net | Host for GraphQL queries. You may use any available gateway that supports GQL queries. If omitted, your node can support GQL queries on locally indexed transactions, but only L1 transactions are indexed by default. |
| GRAPHQL_PORT | Number | 443 | Port for GraphQL queries. Used in conjunction with GRAPHQL_HOST to set up the proxy for GQL queries. |
| START_HEIGHT | Number or "Infinity" | 0 | Starting block height for node synchronization (0 = start from genesis block) |
| STOP_HEIGHT | Number or "Infinity" | "Infinity" | Stop block height for node synchronization (Infinity = keep syncing until stopped) |
| TRUSTED_NODE_URL | String | "https://arweave.net" | Arweave node to use for fetching data |
| TRUSTED_GATEWAY_URL | String | "https://arweave.net" | Arweave node to use for proxying reqeusts |
| TRUSTED_GATEWAYS_URLS | String | TRUSTED_GATEWAY_URL | A JSON map of gateways and priority |
| TRUSTED_GATEWAYS_REQUEST_TIMEOUT_MS | String | "10000" | Request timeout in milliseconds for trusted gateways |
| TRUSTED_ARNS_GATEWAY_URL | String | "https://__NAME__.arweave.dev" | ArNS gateway |
| WEIGHTED_PEERS_TEMPERATURE_DELTA | Number | 0.1 | Any positive number above 0, best to keep 1 or less. Used to determine the sensitivity of which the probability of failing or succeeding peers decreases or increases. |
| INSTANCE_ID | String | "" | Adds an "INSTANCE_ID" field to output logs |
| LOG_FORMAT | String | "simple" | Sets the format of output logs, accepts "simple" and "json" |
| SKIP_CACHE | Boolean | false | If true, skips the local cache and always fetches headers from the node |
| PORT | Number | 4000 | AR.IO node exposed port number |
| SIMULATED_REQUEST_FAILURE_RATE | Number | 0 | Number from 0 to 1, representing the probability of a request failing |
| AR_IO_WALLET | String | "" | Arweave wallet address used for staking and rewards |
| ADMIN_API_KEY | String | Generated | API key used for admin API requests (if not set, it is generated and logged into the console) |
| ADMIN_API_KEY_FILE | String | Generated | Alternative way to set the API key used for admin API requests via filepath, it takes precedence over ADMIN_API_KEY if defined |
| BACKFILL_BUNDLE_RECORDS | Boolean | false | If true, AR.IO node will start indexing missing bundles |
| FILTER_CHANGE_REPROCESS | Boolean | false | If true, all indexed bundles will be reprocessed with the new filters (you can use this when you change the filters) |
| ON_DEMAND_RETRIEVAL_ORDER | String | s3,trusted-gateways,chunks,tx-data | Data source retrieval order for on-demand data requests |
| BACKGROUND_RETRIEVAL_ORDER | String | chunks,s3,trusted-gateways,chunks,tx-data | Data source retrieval order for background data requests (i.e., unbundling) |
| ANS104_UNBUNDLE_FILTER | String | {"never": true} | Only bundles compliant with this filter will be unbundled |
| ANS104_INDEX_FILTER | String | {"never": true} | Only bundles compliant with this filter will be indexed |
| ANS104_DOWNLOAD_WORKERS | String | 5 | Sets the number of ANS-104 bundles to attempt to download in parallel |
| ANS104_UNBUNDLE_WORKERS | Number | 0, or 1 if filters are set | Sets the number of workers used to handle unbundling |
| DATA_ITEM_FLUSH_COUNT_THRESHOLD | Number | 1000 | Sets the number of new data items indexed before flushing to stable data items |
| MAX_FLUSH_INTERVAL_SECONDS | Number | 600 | Sets the maximum time interval in seconds before flushing to stable data items |
| WRITE_ANS104_DATA_ITEM_DB_SIGNATURES | Boolean | false | If true, the data item signatures will be written to the database |
| WRITE_TRANSACTION_DB_SIGNATURES | Boolean | true | If true, the transactions signatures will be written to the database |
| ENABLE_DATA_DB_WAL_CLEANUP | Boolean | false | If true, the data database WAL cleanup worker will be enabled |
| ENABLE_BACKGROUND_DATA_VERIFICATION | Boolean | false | If true, unverified data will be verified in background |
| MAX_DATA_ITEM_QUEUE_SIZE | Number | 100000 | Sets the maximum number of data items to queue for indexing before skipping indexing new data items |
| ARNS_ROOT_HOST | String | undefined | Domain name for ArNS host |
| SANDBOX_PROTOCOL | String | undefined | Protocol setting in process of creating sandbox domains in ArNS (ARNS_ROOT_HOST needs to be set for this env to have any effect) accepts "http" or "https" |
| START_WRITERS | Boolean | true | If true, start indexing blocks, tx, ANS104 bundles |
| RUN_OBSERVER | Boolean | true | If true, runs the Observer alongside the gateway to generate Network compliance reports |
| MIN_RELEASE_NUMBER | string | "0" | Sets the minimum Gateway release version to check while doing a gateway version assessment |
| AR_IO_NODE_RELEASE | string | "0" | Sets the current AR.IO node version to be set on X-AR-IO-Node-Release header on requests to the reference gateway |
| OBSERVER_WALLET | String | undefined | The public wallet address of the wallet being used to sign report upload transactions for Observer |
| CHUNKS_DATA_PATH | string | "data/chunks" | Sets the location for chunked data to be saved. If omitted, chunked data will be stored in the `data` directory |
| CONTIGUOUS_DATA_PATH | string | "data/contiguous" | Sets the location for contiguous data to be saved. If omitted, contiguous data will be stored in the `data` directory |
| HEADERS_DATA_PATH | string | "data/headers" | Sets the location for header data to be saved. If omitted, header data will be stored in the `data` directory |
| SQLITE_DATA_PATH | string | "data/sqlite" | Sets the location for sqlite indexed data to be saved. If omitted, sqlite data will be stored in the `data` directory |
| DUCKDB_DATA_PATH | string | "data/duckdb" | Sets the location for duckdb data to be saved. If omitted, duckdb data will be stored in the `data` directory |
| TEMP_DATA_PATH | string | "data/tmp" | Sets the location for temporary data to be saved. If omitted, temporary data will be stored in the `data` directory |
| LMDB_DATA_PATH | string | "data/LMDB" | Sets the location for LMDB data to be saved. If omitted, LMDB data will be stored in the `data` directory |
| CHAIN_CACHE_TYPE | String | "redis" | Sets the method for caching chain data, defaults to redis if gateway is started with docker-compose, otherwise defaults to LMDB |
| REDIS_CACHE_URL | String (URL) | "redis://localhost:6379" | URL of Redis database to be used for caching |
| REDIS_CACHE_TTL_SECONDS | Number | 28800 | TTL value for Redis cache, defaults to 8 hours (28800 seconds) |
| ENABLE_FS_HEADER_CACHE_CLEANUP | Boolean | false | If true, periodically deletes cached header data |
| NODE_JS_MAX_OLD_SPACE_SIZE | Number | 2048 or 8192, depending on number of workers | Sets the memory limit, in Megabytes, for NodeJs. Default value is 2048 if using less than 2 unbundle workers, otherwise 8192 |
| SUBMIT_CONTRACT_INTERACTIONS | Boolean | true | If true, Observer will submit its generated reports to the AR.IO Network. If false, reports will be generated but not submitted |
| REDIS_MAX_MEMORY | String | 256mb | Sets the max memory allocated to Redis |
| REDIS_EXTRA_FLAGS | String | --save "" --appendonly no | Additional CLI flags passed to Redis |
| WEBHOOK_TARGET_SERVERS | String | undefined | Target servers for webhooks |
| WEBHOOK_INDEX_FILTER | String | {"never": true} | Only emit webhooks for transactions and data items compliant with this filter |
| WEBHOOK_BLOCK_FILTER | String | {"never": true} | Only emit webhooks for blocks compliant with this filter |
| CONTIGUOUS_DATA_CACHE_CLEANUP_THRESHOLD | Number | undefined | Sets the age threshold in seconds; files older than this are candidates for contiguous data cache cleanup |
| ENABLE_MEMPOOL_WATCHER | Boolean | false | If true, the gateway will start indexing pending tx from the mempool |
| MEMPOOL_POLLING_INTERVAL_MS | Number | 30000 | Sets the mempool Polling interval, in milliseconds |
| TAG_SELECTIVITY | String | Refer to config.ts | A JSON map of tag names to selectivity weights used to order SQLite tag joins |
| MAX_EXPECTED_DATA_ITEM_INDEXING_INTERVAL_SECONDS | Number | undefined | Sets the max expected data item indexing interval in seconds |
| BUNDLE_REPAIR_RETRY_INTERVAL_SECONDS | String | "300" (5 minutes) | Interval in seconds for retrying bundles |
| BUNDLE_REPAIR_UPDATE_TIMESTAMPS_INTERVAL_SECONDS | Number | 300 (5 minutes) | Interval in seconds for updating timestamps during bundle repair |
| BUNDLE_REPAIR_BACKFILL_INTERVAL_SECONDS | Number | 900 (15 minutes) | Interval in seconds for backfilling bundles during repair |
| BUNDLE_REPAIR_FILTER_REPROCESS_INTERVAL_SECONDS | Number | 300 (5 minutes) | Interval in seconds for reprocessing filters during bundle repair |
| BUNDLE_REPAIR_RETRY_BATCH_SIZE | String | "1000" | Batch size for retrying bundles |
| APEX_TX_ID | String | undefined | If set, serves this transaction ID's data at the root path (/) |
| APEX_ARNS_NAME | String | undefined | If set, resolves and serves this ArNS name's content at the root path (/) |
| AO_CU_URL | String | undefined | URL of the AO CU to be used for interacting with the AO network. If not set, the default CU from FWD research will be used. |
| NETWORK_AO_CU_URL | String | undefined | URL of the AO CU to be used for fetching ARIO network data. If not set, the default CU from FWD research will be used. |
| AO_MU_URL | String | undefined | URL of the AO MU (Memory Unit) to be used. If not set, the default MU from FWD research will be used. |
| ANT_AO_CU_URL | String | AO_CU_URL | URL of the AO CU to be used for fetching ANT data. If not set, falls back to AO_CU_URL. |
| AO_GRAPHQL_URL | String | undefined | URL of the AO GraphQL endpoint to be used. |
| AO_GATEWAY_URL | String | undefined | URL of the AO Gateway to be used. |
| BUNDLE_DATA_IMPORTER_QUEUE_SIZE | Number | 1000 | The maximum number of bundles to queue for unbundling before skipping |
| VERIFICATION_DATA_IMPORTER_QUEUE_SIZE | Number | 1000 | The maximum number of data imports to queue for verification purposes |
| FS_CLEANUP_WORKER_BATCH_SIZE | Number | 2000 | The number of files to process in each batch during cleanup |
| FS_CLEANUP_WORKER_BATCH_PAUSE_DURATION | Number | 5000 | The pause duration between cleanup batches in milliseconds |
| FS_CLEANUP_WORKER_RESTART_PAUSE_DURATION | Number | 14400000 (4 hours) | The pause duration before restarting cleanup from the beginning in milliseconds |
| ARIO_PROCESS_DEFAULT_CIRCUIT_BREAKER_TIMEOUT_MS | Number | 60000 (60 seconds) | Maximum time allowed for requests to AO for ARIO process state. Requests exceeding this timeout are considered failed and may trigger the circuit breaker if the error threshold is reached. |
| ARIO_PROCESS_DEFAULT_CIRCUIT_BREAKER_ERROR_THRESHOLD_PERCENTAGE | Number | 30 | Percentage of failed requests to AO for ARIO process state that will trigger the circuit breaker to open. Set to 30% to compensate for extended timeouts. |
| ARIO_PROCESS_DEFAULT_CIRCUIT_BREAKER_ROLLING_COUNT_TIMEOUT_MS | Number | 600000 (10 minutes) | Time window for tracking errors when retrieving ARIO process state from AO. The circuit breaker counts failures within this rolling window to determine if the error threshold percentage has been exceeded. |
| ARIO_PROCESS_DEFAULT_CIRCUIT_BREAKER_RESET_TIMEOUT_MS | Number | 1200000 (20 minutes) | Duration the circuit breaker stays in the open state after being triggered. During this period, all requests to AO for ARIO process state will be rejected immediately. After this timeout expires, the circuit breaker transitions to half-open state to test if AO is responsive again. |
| GATEWAY_PEERS_WEIGHTS_CACHE_DURATION_MS | Number | 5000 (5 seconds) | Duration in milliseconds for which gateway peer weights are cached before being recalculated. |
| GATEWAY_PEERS_REQUEST_WINDOW_COUNT | Number | 20 | Size of the array used to calculate the average performance for peer weighting. A longer window provides a better average but has minimal impact on overall performance. |
| ARWEAVE_NODE_IGNORE_URLS | String (comma-separated) | [] | Comma-separated list of Arweave node URLs to ignore when selecting peers. |
| CHUNK_POST_URLS | String (comma-separated) | TRUSTED_NODE_URL/chunk | Comma-separated list of URLs for posting chunks received at /chunk endpoint. |
| CHUNK_POST_CONCURRENCY_LIMIT | Number | 2 | Maximum number of concurrent chunk POST requests allowed. |
| CHUNK_POST_MIN_SUCCESS_COUNT | String | "3" | Minimum count of 200 responses for of a given chunk to be considered properly seeded |
| SECONDARY_CHUNK_POST_URLS | String (comma-separated) | [] | Comma-separated list of additional URLs for posting chunks. These are processed in parallel with primary URLs in a "fire and forget" manner - failures are not blocking. |
| SECONDARY_CHUNK_POST_CONCURRENCY_LIMIT | Number | 2 | Maximum number of concurrent secondary chunk POST requests allowed. These are processed independently of primary chunk posting. |
| SECONDARY_CHUNK_POST_MIN_SUCCESS_COUNT | Number | 1 | Minimum number of successful responses required for a chunk to be considered properly seeded on secondary URLs. Failures are not blocking. |
| CHUNK_POST_RESPONSE_TIMEOUT_MS | Number | undefined | Timeout in milliseconds for chunk POST responses. If not set, no timeout is enforced. |
| CHUNK_POST_ABORT_TIMEOUT_MS | Number | undefined | Timeout in milliseconds after which chunk POST requests will be aborted. If not set, no abort timeout is enforced. |
| AWS_ACCESS_KEY_ID | String | undefined | Access key ID for AWS authentication |
| AWS_SECRET_ACCESS_KEY | String | undefined | Secret access key for AWS authentication |
| AWS_REGION | String | undefined | AWS region for S3 operations |
| AWS_ENDPOINT | String | undefined | Custom AWS endpoint for S3 operations |
| AWS_S3_CONTIGUOUS_DATA_BUCKET | String | undefined | Name of the S3 bucket for storing contiguous data |
| AWS_S3_CONTIGUOUS_DATA_PREFIX | String | undefined | Prefix for contiguous data objects in the S3 bucket |
| AR_IO_SQLITE_BACKUP_S3_BUCKET_NAME | String | undefined | Name of the S3 bucket used for SQLite database backups |
| AR_IO_SQLITE_BACKUP_S3_BUCKET_REGION | String | undefined | Region of the S3 bucket used for SQLite database backups |
| AR_IO_SQLITE_BACKUP_S3_BUCKET_ACCESS_KEY | String | undefined | Access key for the S3 bucket used for SQLite database backups |
| AR_IO_SQLITE_BACKUP_S3_BUCKET_SECRET_KEY | String | undefined | Secret key for the S3 bucket used for SQLite database backups |
| AR_IO_SQLITE_BACKUP_S3_BUCKET_PREFIX | String | undefined | Prefix for SQLite database backup objects in the S3 bucket |