# 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 Environment variables come from two sources: * - set automatically by the Apify platform for each Actor run. * - defined by the Actor owner, either in `.actor/actor.json` or in Apify Console. By default, both kinds of variables are passed only to the Actor **run**, not to the **build**. For variables passed to the build process (Docker build arguments), see . 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. Run-time only System environment variables are set only when the Actor runs. They are not available during the build process, even if you enable **Apply environment variables also to the build process** in the Actor's **Code** > **Environment variables** section. That option only forwards user-defined environment variables to the build; system variables such as `ACTOR_RUN_ID`, `APIFY_TOKEN`, or `ACTOR_DEFAULT_DATASET_ID` are never passed to builds. 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-2515.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-2515.preview.docs.apify.com/platform/actors/running/input-and-output.md#input). | | `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-2515.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-2515.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-2515.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-2515.preview.docs.apify.com/platform/actors/running/runs-and-builds.md#origin) documentation. | | `APIFY_INPUT_SECRETS_PRIVATE_KEY_FILE` | Path to the secret key used to decrypt [Secret inputs](https://pr-2515.preview.docs.apify.com/platform/actors/development/actor-definition/input-schema/secret-input.md). | | `APIFY_INPUT_SECRETS_PRIVATE_KEY_PASSPHRASE` | Passphrase for the input secret key specified in `APIFY_INPUT_SECRETS_PRIVATE_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*). ## Custom environment variables Actor owners can define custom environment variables to pass additional configuration to their Actors. There are two ways to set them up: * * 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. ### 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-2515.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 To set custom variables in Apify Console: 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. Visibility of environment variables in public Actors When you [publish your Actor](https://pr-2515.preview.docs.apify.com/platform/actors/publishing/publish.md), environment variables not marked as **Secret** in Apify Console are visible to anyone on the Actor detail page alongside the source code. Enable **Hide source files from Actor detail** in the Actor's **Settings** to hide both. Secret environment variables are never exposed on the Actor detail page regardless of this setting. Always mark sensitive values as **Secret**. 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-2515.preview.docs.apify.com/platform/actors/development/builds-and-runs/builds.md). ### Use the `Configuration` class For more convenient access to Actor configuration, use the [Configuration](https://pr-2515.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}') ``` ## 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) ``` ## Build-time environment variables The environment variables described above apply only to Actor **runs**. To make a variable available during the Actor's **build** process, you need to opt in explicitly. In this case, the variables function as Docker build arguments. To use them in your Dockerfile, include the `ARG` instruction: ``` ARG MY_BUILD_VARIABLE RUN echo $MY_BUILD_VARIABLE ``` To pass your user-defined environment variables to the build, enable **Apply environment variables also to the build process** in your Actor's **Code** > **Environment variables** section in Apify Console. Only user-defined variables are passed to the build Even with **Apply environment variables also to the build process** enabled, only the variables you define in the Actor's **Environment variables** section are forwarded to the build. The Apify (such as `ACTOR_RUN_ID`, `APIFY_TOKEN`, or `ACTOR_DEFAULT_DATASET_ID`) are never available at build time, since the build is not associated with a specific run. Variables set during the build Build-time environment variables are not suitable for secrets, as they are not encrypted. Once a build starts, its environment variables are frozen into that build's Docker image. To change them, you need to create a new build. Learn more in [Builds](https://pr-2515.preview.docs.apify.com/platform/actors/development/builds-and-runs/builds.md). By leveraging environment variables effectively, you can create more flexible and configurable Actors that adapt to different execution contexts and user requirements.