# Actor environment variables **Learn how to provide your Actor with context that determines its behavior through a plethora of pre-defined environment variables set by the Apify platform.** *** ## How to use environment variables in an Actor You can set up environment variables for your Actor in two ways: * * Environment variable precedence Your local `.actor/actor.json` file overrides variables set in Apify Console. To use Console variables, remove the `environmentVariables` key from the local file. Check out how you can . ## System environment variables Apify sets several system environment variables for each Actor run. These variables provide essential context and information about the Actor's execution environment. Here's a table of key system environment variables: | Environment Variable | Description | | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ACTOR_ID` | ID of the Actor. | | `ACTOR_FULL_NAME` | Full technical name of the Actor, in the format `owner-username/actor-name`. | | `ACTOR_RUN_ID` | ID of the Actor run. | | `ACTOR_BUILD_ID` | ID of the Actor build used in the run. | | `ACTOR_BUILD_NUMBER` | Build number of the Actor build used in the run. | | `ACTOR_BUILD_TAGS` | A comma-separated list of tags of the Actor build used in the run. Note that this environment variable is assigned at the time of start of the Actor and doesn't change over time, even if the assigned build tags change. | | `ACTOR_TASK_ID` | ID of the Actor task. Empty if Actor is run outside of any task, e.g. directly using the API. | | `ACTOR_EVENTS_WEBSOCKET_URL` | Websocket URL where Actor may listen for [events](https://pr-2390.preview.docs.apify.com/platform/actors/development/programming-interface/system-events.md) from Actor platform. | | `ACTOR_STORAGES_JSON` | JSON-encoded unique identifiers of storages associated with the current Actor run. | | `ACTOR_DEFAULT_DATASET_ID` | Unique identifier for the default dataset associated with the current Actor run. | | `ACTOR_DEFAULT_KEY_VALUE_STORE_ID` | Unique identifier for the default key-value store associated with the current Actor run. | | `ACTOR_DEFAULT_REQUEST_QUEUE_ID` | Unique identifier for the default request queue associated with the current Actor run. | | `ACTOR_INPUT_KEY` | Key of the record in the default key-value store that holds the [Actor input](https://pr-2390.preview.docs.apify.com/platform/actors/running/input-and-output.md#input). | | `ACTOR_MAX_PAID_DATASET_ITEMS` | For paid-per-result Actors, the user-set limit on returned results. Do not exceed this limit. | | `ACTOR_MAX_TOTAL_CHARGE_USD` | For pay-per-event Actors, the user-set limit on run cost. Do not exceed this limit. | | `ACTOR_RESTART_ON_ERROR` | If **1**, the Actor run will be restarted if it fails. | | `APIFY_HEADLESS` | If **1**, web browsers inside the Actor should run in headless mode (no windowing system available). | | `APIFY_IS_AT_HOME` | Contains **1** if the Actor is running on Apify servers. | | `ACTOR_MEMORY_MBYTES` | Size of memory allocated for the Actor run, in megabytes. Can be used to optimize memory usage or finetuning of low-level external libraries. | | `ACTOR_PERMISSION_LEVEL` | [Permission level](https://pr-2390.preview.docs.apify.com/platform/actors/running/permissions.md) the Actor is run under (`LIMITED_PERMISSIONS` or `FULL_PERMISSIONS`). This determines what resources in the user’s account the Actor can access. | | `APIFY_PROXY_PASSWORD` | Password for accessing Apify Proxy services. This password enables the Actor to utilize proxy servers on behalf of the user who initiated the Actor run. | | `APIFY_PROXY_PORT` | TCP port number to be used for connecting to Apify Proxy. | | `APIFY_PROXY_STATUS_URL` | URL for retrieving proxy status information. Appending `?format=json` to this URL returns the data in JSON format for programmatic processing. | | `ACTOR_STANDBY_URL` | URL for accessing web servers of Actor runs in the [Actor Standby](https://pr-2390.preview.docs.apify.com/platform/actors/development/programming-interface/standby.md) mode. | | `ACTOR_STARTED_AT` | Date when the Actor was started. | | `ACTOR_TIMEOUT_AT` | Date when the Actor will time out. | | `APIFY_TOKEN` | API token of the user who started the Actor. | | `APIFY_USER_ID` | ID of the user who started the Actor. May differ from the Actor owner. | | `APIFY_USER_IS_PAYING` | If it is `1`, it means that the user who started the Actor is a paying user. | | `ACTOR_WEB_SERVER_PORT` | TCP port for the Actor to start an HTTP server on. This server can be used to receive external messages or expose monitoring and control interfaces. The server also receives messages from the [Actor Standby](https://pr-2390.preview.docs.apify.com/platform/actors/development/programming-interface/standby.md) mode. | | `ACTOR_WEB_SERVER_URL` | Unique public URL for accessing the Actor run web server from the outside world. | | `APIFY_API_PUBLIC_BASE_URL` | Public URL of the Apify API. May be used to interact with the platform programmatically. Typically set to `api.apify.com`. | | `APIFY_DEDICATED_CPUS` | Number of CPU cores reserved for the Actor, based on allocated memory. | | `APIFY_WORKFLOW_KEY` | Identifier used for grouping related runs and API calls together. | | `APIFY_META_ORIGIN` | Specifies how an Actor run was started. Possible values are in [Runs and builds](https://pr-2390.preview.docs.apify.com/platform/actors/running/runs-and-builds.md#origin) documentation. | | `APIFY_INPUT_SECRETS_KEY_FILE` | Path to the secret key used to decrypt [Secret inputs](https://pr-2390.preview.docs.apify.com/platform/actors/development/actor-definition/input-schema/secret-input.md). | | `APIFY_INPUT_SECRETS_KEY_PASSPHRASE` | Passphrase for the input secret key specified in `APIFY_INPUT_SECRETS_KEY_FILE`. | Date format All date-related variables use the UTC timezone and are in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (e.g., *2022-07-13T14:23:37.281Z*). ## Set up environment variables in `actor.json` Actor owners can define custom environment variables in `.actor/actor.json`. All keys from `environmentVariables` will be set as environment variables into the Apify platform after you push Actor to Apify. ``` { "actorSpecification": 1, "name": "dataset-to-mysql", "version": "0.1", "buildTag": "latest", "environmentVariables": { "MYSQL_USER": "my_username", } } ``` Git-workflow with actor.json Be aware that if you define `environmentVariables` in `.actor/actor.json`, it only works with [Apify CLI](https://pr-2390.preview.docs.apify.com/cli). If you use a Git workflow for Actor development, the environment variables will not be set from `.actor/actor.json` and you need to define them in Apify Console. ## Set up environment variables in Apify Console Actor owners can define custom environment variables to pass additional configuration to their Actors. To set custom variables: 1. Go to your Actor's **Source** page in Apify Console 2. Navigate to the **Environment variables** section. 3. Add your custom variables. For sensitive data like API keys or passwords, enable the **Secret** option. This will encrypt the value and redact it from logs to prevent accidental exposure. Build-time variables Once you start a build, you cannot change its environment variables. To use different variables, you must create a new build. Learn more in [Builds](https://pr-2390.preview.docs.apify.com/platform/actors/development/builds-and-runs/builds.md). ## Access environment variables You can access environment variables in your code as follows: * JavaScript * Python In Node.js, use the `process.env` object: ``` import { Actor } from 'apify'; await Actor.init(); // get MYSQL_USER const mysql_user = process.env.MYSQL_USER // print MYSQL_USER to console console.log(mysql_user); await Actor.exit(); ``` In Python, use the `os.environ` dictionary: ``` import os print(os.environ['MYSQL_USER']) from apify import Actor async def main(): async with Actor: # get MYSQL_USER mysql_user = os.environ['MYSQL_USER'] # print MYSQL_USER to console print(mysql_user) ``` ## Use the `Configuration` class For more convenient access to Actor configuration, use the [Configuration](https://pr-2390.preview.docs.apify.com/sdk/js/reference/class/Configuration) class * JavaScript * Python ``` import { Actor } from 'apify'; await Actor.init(); // get current token const token = Actor.config.get('token'); // use different token Actor.config.set('token', 's0m3n3wt0k3n'); await Actor.exit(); ``` ``` from apify import Actor async def main(): async with Actor: old_token = Actor.configuration.token Actor.log.info(f'old_token = {old_token}') # use different token Actor.configuration.token = 's0m3n3wt0k3n' new_token = Actor.configuration.token Actor.log.info(f'new_token = {new_token}') ``` ## Build-time environment variables You can also use environment variables during the Actor's build process. In this case, they function as Docker build arguments. To use them in your Dockerfile, include `ARG` instruction: ``` ARG MY_BUILD_VARIABLE RUN echo $MY_BUILD_VARIABLE ``` Variables set during the build Build-time environment variables are not suitable for secrets, as they are not encrypted. By leveraging environment variables effectively, you can create more flexible and configurable Actors that adapt to different execution contexts and user requirements.