Recent versions of Chainlink ship with sensible defaults for most configuration variables.

Not all env vars are documented here. Any env var that is undocumented is subject to change in future releases. In almost all cases, you should leave any env var not listed here to its default value unless you really understand what you are doing.

To reiterate: if you have an env var set that is not listed here, and you don't know exactly why you have it set, you should remove it!

The env variables listed here are explicitly supported and current as of Chainlink 0.10.14.

• Essential env vars
  • DATABASE_URL
  • ETH_CHAIN_ID
  • ETH_URL
  • LINK_CONTRACT_ADDRESS
• Recommended env vars
  • ETH_HTTP_URL
  • ETH_SECONDARY_URLS
• OCR
  • FEATURE_OFFCHAIN_REPORTING
  • P2P_ANNOUNCE_IP
  • P2P_ANNOUNCE_PORT
  • P2P_BOOTSTRAP_PEERS
  • P2P_LISTEN_IP
  • P2P_LISTEN_PORT
  • P2P_PEER_ID
• Keeper
  • KEEPER_DEFAULT_TRANSACTION_QUEUE_DEPTH
  • KEEPER_MAXIMUM_GRACE_PERIOD
  • KEEPER_MINIMUM_REQUIRED_CONFIRMATIONS
  • KEEPER_REGISTRY_CHECK_GAS_OVERHEAD
  • KEEPER_REGISTRY_PERFORM_GAS_OVERHEAD
  • KEEPER_REGISTRY_SYNC_INTERVAL
• TLS
  • CHAINLINK_TLS_HOST
  • CHAINLINK_TLS_PORT
  • CHAINLINK_TLS_REDIRECT
  • TLS_CERT_PATH
  • TLS_KEY_PATH
• Gas controls
  • ETH_GAS_LIMIT_DEFAULT
  • ETH_GAS_LIMIT_MULTIPLIER
  • ETH_GAS_LIMIT_TRANSFER
  • ETH_GAS_BUMP_PERCENT
  • ETH_GAS_BUMP_THRESHOLD
  • ETH_GAS_BUMP_TX_DEPTH
  • ETH_GAS_BUMP_WEI
  • ETH_GAS_PRICE_DEFAULT
  • ETH_MAX_GAS_PRICE_WEI
  • ETH_MIN_GAS_PRICE_WEI
  • GAS_ESTIMATOR_MODE
  • BLOCK_HISTORY_ESTIMATOR_BATCH_SIZE
  • BLOCK_HISTORY_ESTIMATOR_BLOCK_HISTORY_SIZE
  • BLOCK_HISTORY_ESTIMATOR_BLOCK_DELAY
  • BLOCK_HISTORY_ESTIMATOR_TRANSACTION_PERCENTILE
• Other env vars
  • ENABLE_EXPERIMENTAL_ADAPTERS
  • ENABLE_LEGACY_JOB_PIPELINE
  • BALANCE_MONITOR_ENABLED
  • FEATURE_CRON_V2
  • FEATURE_EXTERNAL_INITIATORS
  • FEATURE_FLUX_MONITOR
  • FEATURE_FLUX_MONITOR_V2
  • FEATURE_WEBHOOK_V2
  • ADMIN_CREDENTIALS_FILE
  • ALLOW_ORIGINS
  • CHAINLINK_PORT
  • CLIENT_NODE_URL
  • DATABASE_BACKUP_FREQUENCY
  • DATABASE_BACKUP_MODE
  • DATABASE_BACKUP_URL
  • DATABASE_BACKUP_DIR
  • ETH_DISABLED
  • EXPLORER_URL
  • EXPLORER_ACCESS_KEY
  • EXPLORER_SECRET
  • TELEMETRY_INGRESS_URL
  • TELEMETRY_INGRESS_SERVER_PUB_KEY
  • TELEMETRY_INGRESS_LOGGING
  • JSON_CONSOLE
  • LOG_LEVEL
  • LOG_SQL
  • LOG_SQL_MIGRATIONS
  • LOG_TO_DISK
  • MIN_INCOMING_CONFIRMATIONS
  • ETH_NONCE_AUTO_SYNC
  • ETH_FINALITY_DEPTH
  • ETH_HEAD_TRACKER_HISTORY_DEPTH
  • ETH_HEAD_TRACKER_MAX_BUFFER_SIZE
  • ETH_HEAD_TRACKER_SAMPLING_INTERVAL
  • BLOCK_BACKFILL_DEPTH
  • BLOCK_BACKFILL_SKIP
  • ETH_LOG_BACKFILL_BATCH_SIZE
  • ETH_TX_REAPER_INTERVAL
  • ETH_TX_REAPER_THRESHOLD
  • ETH_TX_RESEND_AFTER_THRESHOLD
  • MINIMUM_CONTRACT_PAYMENT_LINK_JUELS
  • MINIMUM_REQUEST_EXPIRATION
  • MINIMUM_SERVICE_DURATION
  • OPERATOR_CONTRACT_ADDRESS
  • ORM_MAX_IDLE_CONNS
  • ORM_MAX_OPEN_CONNS
  • ROOT
  • SECURE_COOKIES
  • SESSION_TIMEOUT
• Advanced
  • ETH_MAX_IN_FLIGHT_TRANSACTIONS
  • ETH_MAX_QUEUED_TRANSACTIONS
  • DEFAULT_HTTP_TIMEOUT
• Misc notes

Essential env vars

DATABASE_URL

Required

• Default: none

The PostgreSQL URI to connect to your database. See the Running a Chainlink Node for an example.

ETH_CHAIN_ID

• Default: "1" (Ethereum mainnet)

Chainlink currently only supports one chain at a time. This var specifies the chain ID to use for transactions. It must match the chain ID of the connected RPC node.

curl -k -X POST -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","method":"eth_chainId","id":1}' http://localhost:8545

ETH_URL

• Default: "ws://localhost:8546"

This is the websocket address of the Ethereum client that the Chainlink node will connect to. All interaction with the Ethereum blockchain will occur through this connection.

LINK_CONTRACT_ADDRESS

• Default: automatic based on Chain ID

The address of the LINK token contract. Used for displaying the node account's LINK balance. For supported chains, this is automatically set based on the given chain ID. For unsupported chains, you will need to supply it yourself.

Recommended env vars

ETH_HTTP_URL

• Default: none

This should be set to the http URL that points to the same eth node as the primary. If set, Chainlink will automatically use HTTP mode for heavy requests, which can improve reliability.

ETH_SECONDARY_URLS

• Default: none

If set, transactions will also be broadcast to this secondary ethereum node. This allows transaction broadcasting to be more robust in the face of primary ethereum node bugs or failures.

It is recommended to set at least one secondary eth node here that is different from your primary.

Multiple URLs can be specified as a comma-separated list e.g.

ETH_SECONDARY_URLS=https://example.com/1,https://example.text/2,...

OCR

This section only applies if you are running offchain reporting jobs.

FEATURE_OFFCHAIN_REPORTING

• Default: "false"

Set to true to enable OCR jobs.

P2P_ANNOUNCE_IP

• Default: none

Should be set as the externally reachable IP address of the chainlink node.

P2P_ANNOUNCE_PORT

• Default: none

Should be set as the externally reachable port of the chainlink node.

P2P_BOOTSTRAP_PEERS

• Default: none

Default set of bootstrap peers.

P2P_LISTEN_IP

• Default: "0.0.0.0"

The default IP address to bind to.

P2P_LISTEN_PORT

• Default: none

The port to listen on. If left blank, chainlink will randomly select a different port each time it boots. It is highly recommended to set this to a static value to avoid network instability.

P2P_PEER_ID

• Default: none

The default peer ID to use for OCR jobs. If unspecified, uses the first available peer ID.

Keeper

KEEPER_DEFAULT_TRANSACTION_QUEUE_DEPTH

• Default: "1"

Controls the queue size for DropOldestStrategy in Keeper.

Set to 0 to use SendEvery strategy instead.

KEEPER_MAXIMUM_GRACE_PERIOD

• Default: "100"

The maximum number of blocks that a keeper will wait after performing an upkeep before it resumes checking that upkeep

KEEPER_MINIMUM_REQUIRED_CONFIRMATIONS

• Default: "12"

THe minimum number of confirmations that a keeper registry log
needs before it is handled by the RegistrySynchronizer.

KEEPER_REGISTRY_CHECK_GAS_OVERHEAD

• Default: "200000"

The amount of extra gas to provide checkUpkeep() calls
to account for the gas consumed by the keeper registry.

KEEPER_REGISTRY_PERFORM_GAS_OVERHEAD

• Default: "150000"

The amount of extra gas to provide performUpkeep() calls to account for the gas consumed by the keeper registry

KEEPER_REGISTRY_SYNC_INTERVAL

• Default: "30m"

The interval in which the RegistrySynchronizer performs a full sync of the keeper registry contract it is tracking.

TLS

This section applies if you want to enable TLS security on your chainlink node.

CHAINLINK_TLS_HOST

• Default: none

The hostname configured for TLS to be used by the Chainlink node. This is useful if you've configured a domain name specific for your Chainlink node.

CHAINLINK_TLS_PORT

• Default: "6689"

The port used for HTTPS connections. Set to 0 to disable HTTPS (disabling HTTPS also relieves Chainlink of the requirement for a TLS certificate).

CHAINLINK_TLS_REDIRECT

• Default: "false"

Forces TLS redirect for unencrypted connections.

TLS_CERT_PATH

• Default: none

Location of the TLS certificate file. Example: /home/$USER/.chainlink/tls/server.crt

TLS_KEY_PATH

• Default: none

Location of the TLS private key file. Example: /home/$USER/.chainlink/tls/server.key

Gas controls

Use this section to tune your node's gas limits and pricing. In most cases, leaving these values at their defaults should give good results.

ETH_GAS_LIMIT_DEFAULT

• Default: automatically set based on Chain ID, typically 500000

The default gas limit for outgoing transactions. This should not need to be changed in most cases.
Some job types (e.g. keeper) may set their own gas limit unrelated to this value.

ETH_GAS_LIMIT_MULTIPLIER

• Default: "1.0"

A factor by which a transaction's GasLimit is
multiplied before transmission. So if the value is 1.1, and the GasLimit for
a transaction is 10, 10% will be added before transmission.

This factor is always applied, so includes Optimism L2 transactions which
uses a default gas limit of 1 and is also applied to EthGasLimitDefault.

ETH_GAS_LIMIT_TRANSFER

• Default: automatically set based on Chain ID, typically 21000

The gas limit used for an ordinary eth->eth transfer.

ETH_GAS_BUMP_PERCENT

• Default: automatic based on chain ID

The percentage by which to bump gas on a transaction that has exceeded ETH_GAS_BUMP_THRESHOLD. The larger of ETH_GAS_BUMP_PERCENT and ETH_GAS_BUMP_WEI is taken for gas bumps.

ETH_GAS_BUMP_THRESHOLD

• Default: automatic based on chain ID

Chainlink can be configured to automatically bump gas on transactions that have been stuck waiting in the mempool for at least this many blocks. Set to 0 to disable gas bumping completely.

ETH_GAS_BUMP_TX_DEPTH

• Default: "10"

The number of transactions to gas bump starting from oldest. Set to 0 for no limit (i.e. bump all).

ETH_GAS_BUMP_WEI

• Default: automatic based on chain ID

The minimum fixed amount of wei by which gas is bumped on each transaction attempt.

ETH_GAS_PRICE_DEFAULT

• Default: automatic based on chain ID

The default gas price to use when submitting transactions to the blockchain. Will be overridden by the in-built GasUpdater, and may be increased if gas bumping is enabled.

Can be used with the chainlink setgasprice to be updated while the node is still running.

ETH_MAX_GAS_PRICE_WEI

• Default: automatic based on chain ID

Chainlink will never pay more than this for a transaction.

ETH_MIN_GAS_PRICE_WEI

• Default: automatic based on chain ID

Chainlink will never pay less than this for a transaction.

It is possible to force chainlink to use a fixed gas price by setting a combination of these, e.g.

ETH_MAX_GAS_PRICE_WEI=100
ETH_MIN_GAS_PRICE_WEI=100
ETH_GAS_PRICE_DEFAULT=100
ETH_GAS_BUMP_THRESHOLD=0
GAS_ESTIMATOR_MODE="FixedPrice"

GAS_ESTIMATOR_MODE

• Default: automatic, based on chain ID

Controls what type of gas estimator is used. Possible values are: "BlockHistory", "Optimism" and "FixedPrice".

• FixedPrice uses the configured values for gas price
• BlockHistory dynamically adjusts default gas price based on heuristics from mined blocks.
• Optimism is a special mode only for use with the Optimism blockchain

BLOCK_HISTORY_ESTIMATOR_BATCH_SIZE

• Default: automatic, based on chain ID, typically 4

Sets the maximum number of blocks to fetch in one batch in the block history estimator.
If the env var BLOCK_HISTORY_ESTIMATOR_BATCH_SIZE is set to 0, it defaults to ETH_RPC_DEFAULT_BATCH_SIZE.

BLOCK_HISTORY_ESTIMATOR_BLOCK_HISTORY_SIZE

• Default: automatic, based on chain ID

Controls the number of past blocks to keep in memory to use as a basis for calculating a percentile gas price.

BLOCK_HISTORY_ESTIMATOR_BLOCK_DELAY

• Default: automatic, based on chain ID

Controls the number of blocks that the block history estimator trails behind head.
E.g. if this is set to 3, and we receive block 10, block history estimator will fetch block 7.

CAUTION: You might be tempted to set this to 0 to use the latest possible
block, but it is possible to receive a head BEFORE that block is actually
available from the connected node via RPC. In this case you will get false
"zero" blocks that are missing transactions.

BLOCK_HISTORY_ESTIMATOR_TRANSACTION_PERCENTILE

• Default: "60"

Must be in range 0-100.

Only has an effect if gas updater is enabled. Specifies percentile gas price to choose. E.g. if the block history contains four transactions with gas prices [100, 200, 300, 400] then picking 25 for this number will give a value of 200. If the calculated gas price is higher than ETH_GAS_PRICE_DEFAULT then the higher price will be used as the base price for new transactions.

Think of this number as an indicator of how aggressive you want your node to price its transactions.

Setting this number higher will cause Chainlink to select higher gas prices.

Setting it lower will tend to set lower gas prices.

Other env vars

ENABLE_EXPERIMENTAL_ADAPTERS

• Default: "false"

Enables experimental adapters.

ENABLE_LEGACY_JOB_PIPELINE

• Default: "true"

Enables the legacy job pipeline

BALANCE_MONITOR_ENABLED

• Default: "true"

Enables Balance Monitor feature.

FEATURE_CRON_V2

• Default: "true"

Enables the Cron v2 feature.

FEATURE_EXTERNAL_INITIATORS

• Default: "false"

Enables the External Initiator feature.

FEATURE_FLUX_MONITOR

• Default: "true"

Enables the Flux Monitor job type.

FEATURE_FLUX_MONITOR_V2

• Default: "true"

Enables the Flux Monitor v2 job type.

FEATURE_WEBHOOK_V2

• Default: "false"

Enables the Webhook v2 job type.

ADMIN_CREDENTIALS_FILE

• Default: $CHAINLINK_ROOT/apicredentials

ADMIN_CREDENTIALS_FILE optionally points to a text file containing admin credentials for logging in. It is useful for running client CLI commands and has no effect when passed to a running node.

The file should contain two lines, the first line is the username and second line is the password.
e.g.

myusername@example.com
mysecurepassw0rd

ALLOW_ORIGINS

• Default: "http://localhost:3000,http://localhost:6688"

Specifies the addresses/URLs of allowed connections to the API on CLIENT_NODE_URL. Input may be a comma-separated (no spaces) list. You may experience CORS issues if this is not set correctly.

CHAINLINK_PORT

• Default: "6688"

Port used for the Chainlink Node API Reference and GUI.

CLIENT_NODE_URL

• Default: "http://localhost:6688"

This is the URL that you will use to interact with the node, including the GUI. It only has effect when using the chainlink client to run CLI commands.

DATABASE_BACKUP_FREQUENCY

• Default: "0"

If set to a positive duration and DATABASE_BACKUP_MODE is not none, will dump the database at this regular interval.

Example:

DATABASE_BACKUP_FREQUENCY=1h

DATABASE_BACKUP_MODE

• Default: "none"

Set the mode for automatic database backups. Can be one of none, lite, full. If enabled, Chainlink will automatically dump database backups at regular intervals.

none disables.
lite dumps small, essential tables.
full dumps the entire database.

DATABASE_BACKUP_URL

If specified, the automatic database backup will pull from this URL rather than the main DATABASE_URL. It is recommended to set this value to a read replica if you have one to avoid excessive load on the main database.

DATABASE_BACKUP_DIR

Configures the directory for saving the backup file, if it's to be different from default one located in the ROOT directory

ETH_DISABLED

• Default: "false"

Disable connection to eth node entirely. This can be useful in certain cases, e.g. to spin up a chainlink node and add jobs without having it execute anything.

EXPLORER_URL

• Default: none

The Explorer websocket URL for the node to push stats to.

EXPLORER_ACCESS_KEY

• Default: none

The access key for authenticating with the Explorer.

EXPLORER_SECRET

• Default: none

The secret for authenticating with the Explorer.

TELEMETRY_INGRESS_URL

• Default: none

The URL to connect to for sending telemetry.

TELEMETRY_INGRESS_SERVER_PUB_KEY

• Default: none

The public key of the telemetry server.

TELEMETRY_INGRESS_LOGGING

• Default: "false"

Toggles verbose logging of the raw telemetry messages being sent.

JSON_CONSOLE

• Default: "false"

Set to true to enable JSON logging. Otherwise will log in a human-friendly console format.

LOG_LEVEL

• Default: "info"

The LOG_LEVEL environment variable determines both what is printed on the screen and what is written to the logfile, located at $ROOT/log.jsonl.

The available options are:

• "debug"
• "info"
• "warn"
• "error"
• "panic"

LOG_SQL

• Default: "false"

Tells Chainlink to log all SQL statements made using the default logger.

LOG_SQL_MIGRATIONS

• Default: "true"

Tells Chainlink to log all SQL migrations made using the default logger.

LOG_TO_DISK

• Default: "true"

Enables or disables the node writing to the $ROOT/log.jsonl file.

MIN_INCOMING_CONFIRMATIONS

• Default: "3"

The number of block confirmations to wait before kicking off a job run. Setting this to a lower value improves node response time at the expense of occasionally submitting duplicate transactions in the event of chain re-orgs (duplicate transactions are harmless but cost some eth).

ETH_NONCE_AUTO_SYNC

• Default: "true"

Enables/disables running the NonceSyncer on application start

ETH_FINALITY_DEPTH

• Default: automatically set based on Chain ID, typically 50

The number of blocks after which an ethereum transaction is considered "final"
BlocksConsideredFinal determines how deeply we look back to ensure that transactions are confirmed onto the longest chain
There is not a large performance penalty to setting this relatively high (on the order of hundreds)

It is practically limited by the number of heads we store in the database and should be less than this with a comfortable margin.
If a transaction is mined in a block more than this many blocks ago, and is reorged out, we will NOT retransmit this transaction and undefined behaviour can occur including gaps in the nonce sequence that require manual intervention to fix.
Therefore, this number represents a number of blocks we consider large enough that no re-org this deep will ever feasibly happen.

ETH_HEAD_TRACKER_HISTORY_DEPTH

• Default: automatically set based on Chain ID, typically 100

Tracks the top N block numbers to keep in the heads database table.
Note that this can easily result in MORE than N records since in the case of re-orgs we keep multiple heads for a particular block height.
This number should be at least as large as ETH_FINALITY_DEPTH.
There may be a small performance penalty to setting this to something very large (10,000+)

ETH_HEAD_TRACKER_MAX_BUFFER_SIZE

• Default: "3"

The maximum number of heads that may be
buffered in front of the head tracker before older heads start to be
dropped. You may think of it as something like the maximum permittable "lag"
for the head tracker before we start dropping heads to keep up.

ETH_HEAD_TRACKER_SAMPLING_INTERVAL

• Default: automatically set based on Chain ID, typically 1s

The minumum amout of time between delivering new heads to different services of Chainlink node.

BLOCK_BACKFILL_DEPTH

• Default: "10"

It specifies the number of blocks before the current head that the log broadcaster will try to re-consume logs from, e.g. after adding a new job

BLOCK_BACKFILL_SKIP

• Default: "false"

It enables skipping of very long log backfills - for example in a situation when the node is started after being offline for a long time.
This might be useful on fast chains and if only recent chain events are relevant

ETH_LOG_BACKFILL_BATCH_SIZE

• Default: "100"

Controls the batch size for calling FilterLogs when backfilling missing or recent logs

ETH_TX_REAPER_INTERVAL

• Default: "1h"

Controls how often the eth tx reaper should run, used to delete old confirmed/fatally_errored transaction records from the database.

ETH_TX_REAPER_THRESHOLD

• Default: "24h"

Represents how long any confirmed/fatally_errored eth_txes will hang around in the database.
If the eth_tx is confirmed but still below ETH_FINALITY_DEPTH it will not be deleted even if it was created at a time older than this value.

EXAMPLE:
With: EthTxReaperThreshold=1h and EthFinalityDepth=50
If current head is 142, any eth_tx confirmed in block 91 or below will be reaped as long as its created_at was more than EthTxReaperThreshold ago

Set to 0 to disable eth_tx reaping

ETH_TX_RESEND_AFTER_THRESHOLD

• Default: automatically set based on Chain ID, typically 1m

Controls how long the ethResender will wait before
re-sending the latest eth_tx_attempt. This is designed a as a fallback to
protect against the eth nodes dropping txes (it has been anecdotally
observed to happen), networking issues or txes being ejected from the mempool.

See eth_resender.go for more details

MINIMUM_CONTRACT_PAYMENT_LINK_JUELS

• Default: automatically set based on Chain ID, typically 100000000000000 (0.0001 LINK) on all chains except mainnet, where it is 1 LINK

For jobs that use the EthTx adapter, this is the minimum payment amount in order for the node to accept and process the job. Since there are no decimals on the EVM, the value is represented like wei.

MINIMUM_REQUEST_EXPIRATION

• Default: "300"

The minimum allowed request expiration for a Service Agreement.

MINIMUM_SERVICE_DURATION

• Default: "0s"

The shortest duration from now that a service is allowed to run.

OPERATOR_CONTRACT_ADDRESS

• Default: none

The address of the Operator contract. Used to filter the contract addresses the node should listen to for Run Logs.

ORM_MAX_IDLE_CONNS

• Default: "10"

Maximum number of idle database connections to keep open by the ORM. Reducing this can help if you are hitting postgres connection limits, at the expense of poorer chainlink node performance.

ORM_MAX_OPEN_CONNS

• Default: "20"

Maximum number of open database connections from the ORM. Reducing this can help if you are hitting postgres connection limits, at the expense of poorer chainlink node performance.

ROOT

• Default: "~/.chainlink"

This is the directory where the log.jsonl file resides. log.jsonl is the log as written by the Chainlink node, depending on the LOG_LEVEL specified by the environment variable's value.

SECURE_COOKIES

• Default: "true"

Requires the use of secure cookies for authentication. Set to false to enable standard http requests along with CHAINLINK_TLS_PORT=0.

SESSION_TIMEOUT

• Default: "15m"

This value determines the amount of idle time to elapse before the GUI signs out users from their sessions.

Advanced

Caution: only change these if you really know what you are doing. Setting these wrongly can cause your node to get permanently stuck, requiring manual intervention to fix.

ETH_MAX_IN_FLIGHT_TRANSACTIONS

• Default: 16

Controls how many transactions are allowed to be "in-flight" i.e. broadcast but unconfirmed at any one time. You can consider this a form of transaction throttling.

The default is set conservatively at 16 because this is a pessimistic minimum that both geth and parity will hold without evicting local transactions. If your node is falling behind and you need higher throughput, you can increase this setting, but you must make sure that your eth node is configured properly otherwise you can get nonce gapped.

0 value disables the limit. Use with caution.

ETH_MAX_QUEUED_TRANSACTIONS

• Default: automatically set based on Chain ID, typically 250

The maximum number of unbroadcast transactions per key that are allowed to be enqueued before jobs will start failing and rejecting send of any further transactions. This represents a sanity limit and generally indicates a problem with your eth node (transactions are not getting mined).

Do NOT blindly increase this value thinking it will fix things if you start hitting this limit because transactions are not getting mined, you will instead only make things worse.

In deployments with very high burst rates, or on chains with large re-orgs, you may consider increasing this.

0 value disables any limit on queue size. Use with caution.

DEFAULT_HTTP_TIMEOUT

• Default: 15s

The default timeout for HTTP requests.

Misc notes

10ms
1h15m
42m30s