All configuration is via environment variables. Create a .env file or set them directly in your environment.
The admin UI setup wizard at http://localhost:3001 can generate a .env file for you.
Variable Default Description PORT3000Public server port HOST0.0.0.0Public server bind address BASE_DOMAINlocalhostBase domain for ArNS subdomain routing ROOT_HOST_CONTENT(empty) ArNS name or txId to serve at root domain RESTRICT_TO_ROOT_HOSTfalseOnly serve root domain content (404 for subdomains/txIds) GRAPHQL_PROXY_URL(empty) Upstream GraphQL endpoint for /graphql proxy
ROOT_HOST_CONTENT accepts either an ArNS name or a transaction ID (auto-detected by format):
# ArNS name ROOT_HOST_CONTENT = wayfinder # Transaction ID (43-char base64url) ROOT_HOST_CONTENT = bNbA3TEQVL60xlgCcqdz4ZPHFZ711cZ3hmkpGttDt_U When set, the root domain serves this content instead of the info page. The info page moves to /wayfinder/info.
Variable Default Description DEFAULT_MODEproxyOperating mode: proxy or route ALLOW_MODE_OVERRIDEtrueAllow ?mode= query parameter to override
Modes:
proxy - Fetch, verify, and serve content through the routerroute - Redirect clients directly to a gateway URL
Controls where content is fetched from.
Variable Default Description ROUTING_STRATEGYfastestGateway selection strategy ROUTING_GATEWAY_SOURCEnetworkWhere to get the gateway list ROUTING_STATIC_GATEWAYS(see below) Comma-separated gateway URLs (when source=static) TRUSTED_PEER_GATEWAYhttps://turbo-gateway.comGateway for peer list (when source=trusted-peers) TRUSTED_ARIO_GATEWAYS(empty) Trusted gateways (when source=trusted-ario)
Strategy Behavior Best For fastestConcurrent ping, use first responder Lowest latency randomRandom selection from healthy gateways Load distribution round-robinSequential rotation through gateways Predictable distribution temperatureWeighted selection based on recent performance Production (recommended)
The temperature strategy tracks per-gateway latency and success rate. Better-performing gateways get more traffic, but slower gateways still receive some requests to detect improvements.
Source Behavior networkAll ar.io gateways from the on-chain registry (recommended) trusted-peersPeer list from TRUSTED_PEER_GATEWAY trusted-arioSpecific gateways from TRUSTED_ARIO_GATEWAYS staticManual list from ROUTING_STATIC_GATEWAYS
Controls content integrity verification.
Variable Default Description VERIFICATION_ENABLEDtrueEnable content hash verification VERIFICATION_GATEWAY_SOURCEtop-stakedSource for trusted gateways VERIFICATION_GATEWAY_COUNT3Number of gateways to query for verification VERIFICATION_STATIC_GATEWAYS(see below) Comma-separated URLs (when source=static) VERIFICATION_RETRY_ATTEMPTS3Gateways to try before failing ARNS_CONSENSUS_THRESHOLD2Minimum gateways that must agree on ArNS resolution
Source Behavior top-stakedTop N gateways by stake (economic security, recommended) staticManual list from VERIFICATION_STATIC_GATEWAYS
Variable Default Description CONTENT_CACHE_ENABLEDtrueEnable verified content cache CONTENT_CACHE_MAX_SIZE_BYTES53687091200 (50GB)Maximum total cache size CONTENT_CACHE_MAX_ITEM_SIZE_BYTES2147483648 (2GB)Maximum single item size CONTENT_CACHE_PATH(empty) Disk path for persistence (empty = in-memory only) ARNS_CACHE_TTL_MS300000 (5min)ArNS resolution cache TTL
For production, enable disk persistence:
CONTENT_CACHE_PATH = ./data/content-cache When set:
LRU holds metadata only (low memory footprint)
Content stored as files on disk (<sha256>.bin + <sha256>.meta.json)
Cache survives restarts
Atomic writes via temp file + rename for crash safety
The admin UI runs on a separate port for security.
Variable Default Description ADMIN_UI_ENABLEDtrueEnable admin UI server ADMIN_PORT3001Admin server port (must differ from PORT) ADMIN_HOST127.0.0.1Admin bind address ADMIN_TOKEN(empty) Bearer token for auth (required when not localhost) ADMIN_OPEN_BROWSERtrueAuto-open browser on startup
When ADMIN_HOST=0.0.0.0, you must set ADMIN_TOKEN to protect the admin UI.
Variable Default Description RETRY_ATTEMPTS3Retry attempts for failed requests RETRY_DELAY_MS100Delay between retries CIRCUIT_BREAKER_THRESHOLD3Failures before marking gateway unavailable CIRCUIT_BREAKER_RESET_MS60000 (1min)Time before retrying a broken gateway GATEWAY_HEALTH_TTL_MS300000 (5min)Health status cache TTL STREAM_TIMEOUT_MS120000 (2min)Per-chunk stream read timeout
Variable Default Description TELEMETRY_ENABLEDtrueEnable telemetry collection TELEMETRY_ROUTER_IDrouter-{timestamp}Instance identifier TELEMETRY_DB_PATH./data/telemetry.dbSQLite database path TELEMETRY_RETENTION_DAYS30Data retention period TELEMETRY_SAMPLE_SUCCESS0.1Sampling rate for successful requests (0.0-1.0) TELEMETRY_SAMPLE_ERRORS1.0Sampling rate for errors
Variable Default Description RATE_LIMIT_ENABLEDfalseEnable per-IP rate limiting RATE_LIMIT_WINDOW_MS60000 (1min)Rate limit window RATE_LIMIT_MAX_REQUESTS1000Max requests per IP per window
Variable Default Description MODERATION_ENABLEDfalseEnable content moderation MODERATION_BLOCKLIST_PATH./data/blocklist.jsonBlocklist file (auto-created, hot-reloaded) MODERATION_ADMIN_TOKEN(empty) Bearer token for moderation API
Proxy Arweave node API endpoints (/info, /tx/{id}, /block/height/{h}, etc.).
Variable Default Description ARWEAVE_API_ENABLEDfalseEnable Arweave API proxy ARWEAVE_READ_NODES(Arweave tip nodes) Nodes for GET requests ARWEAVE_WRITE_NODES(falls back to read) Nodes for POST requests ARWEAVE_API_CACHE_ENABLEDtrueCache API responses
Background latency probing for the temperature routing strategy.
Variable Default Description PING_ENABLEDtrueEnable ping service PING_INTERVAL_HOURS4How often to refresh ping data PING_GATEWAY_COUNT50Gateways to ping each round PING_TIMEOUT_MS5000Timeout per ping PING_CONCURRENCY10Maximum concurrent pings
Variable Default Description SHUTDOWN_DRAIN_TIMEOUT_MS15000 (15s)Grace period for in-flight requests SHUTDOWN_TIMEOUT_MS30000 (30s)Total shutdown timeout
Variable Default Description LOG_LEVELinfoLog level: trace, debug, info, warn, error, fatal
# .env - Production example # Server PORT = 3000 HOST = 0.0.0.0 BASE_DOMAIN = yourdomain.com ROOT_HOST_CONTENT = your-arns-name # Mode DEFAULT_MODE = proxy ALLOW_MODE_OVERRIDE = false # Routing ROUTING_STRATEGY = temperature ROUTING_GATEWAY_SOURCE = network # Verification VERIFICATION_ENABLED = true VERIFICATION_GATEWAY_SOURCE = top-staked VERIFICATION_GATEWAY_COUNT = 3 ARNS_CONSENSUS_THRESHOLD = 2 # Cache CONTENT_CACHE_ENABLED = true CONTENT_CACHE_PATH = ./data/content-cache CONTENT_CACHE_MAX_SIZE_BYTES = 53687091200 # Admin ADMIN_UI_ENABLED = true ADMIN_PORT = 3001 ADMIN_HOST = 127.0.0.1 # Telemetry TELEMETRY_ENABLED = true TELEMETRY_DB_PATH = ./data/telemetry.db # Rate Limiting RATE_LIMIT_ENABLED = true RATE_LIMIT_MAX_REQUESTS = 1000 How is this guide?
ar.io Documentation