Actor configuration

Copy for LLM

The Actor class is configured through the Configuration class, which reads its settings from environment variables. When running on the Apify platform or through the Apify CLI, configuration is automatic — manual setup is only needed for custom requirements.

If you need some special configuration, you can adjust it either through the Configuration class directly, or by setting environment variables when running the Actor locally.

To see the full list of configuration options, check the Configuration class or the list of environment variables that the Actor understands.

Configuring from code

This will cause the Actor to persist its state every 10 seconds:

Run on

import asyncio
from datetime import timedelta

from apify import Actor, Configuration, Event


async def main() -> None:
    configuration = Configuration(
        persist_state_interval=timedelta(seconds=10)
        # Set other configuration options here as needed.
    )

    async with Actor(configuration=configuration):
        # Define a handler that will be called for every persist state event.
        async def save_state() -> None:
            await Actor.set_value('STATE', 'Hello, world!')

        # The save_state handler will be called every 10 seconds now.
        Actor.on(Event.PERSIST_STATE, save_state)


if __name__ == '__main__':
    asyncio.run(main())

Configuring via environment variables

All configuration options can also be set via environment variables. Most options are read from an environment variable named after the option in uppercase. Many options also accept several aliases, commonly with an APIFY_, ACTOR_, or CRAWLEE_ prefix. For the full list of configuration options, see the Configuration API reference.

For example, this Actor run will keep the contents of its local storages instead of purging them on start:

APIFY_PURGE_ON_START=0 apify run

Commonly used options

The following table lists a few options you are most likely to set yourself. When running on the Apify platform or via the Apify CLI, the platform-related options are populated automatically.

Option	Environment variable	Default	Description
token	APIFY_TOKEN	None	API token used to authenticate calls to the Apify API.
proxy_password	APIFY_PROXY_PASSWORD	None	Password for Apify Proxy.
purge_on_start	APIFY_PURGE_ON_START	True	Whether to purge local storages when the Actor starts.
persist_state_interval	APIFY_PERSIST_STATE_INTERVAL_MILLIS	1 min	How often the PERSIST_STATE event is emitted (the variable is in milliseconds).
log_level	APIFY_LOG_LEVEL	'INFO'	Minimum severity of log messages that are printed.
headless	APIFY_HEADLESS	True	Whether to run browsers in headless mode.
storage_dir	APIFY_LOCAL_STORAGE_DIR	'./storage'	Directory holding local storages when running outside the platform.
is_at_home	APIFY_IS_AT_HOME	False	Set by the platform. True when the Actor runs on Apify.

Reading the runtime environment

The Actor.get_env method returns a dictionary with all APIFY_* environment variables parsed into their typed values. This is useful for inspecting the Actor's runtime context, such as the Actor ID, run ID, or default storage IDs. Variables that are not set or are invalid will have a value of None.

Run on

import asyncio

from apify import Actor


async def main() -> None:
    async with Actor:
        env = Actor.get_env()

        Actor.log.info(f'Actor ID: {env.get("id")}')
        Actor.log.info(f'Run ID: {env.get("run_id")}')
        Actor.log.info(f'Default dataset ID: {env.get("default_dataset_id")}')
        Actor.log.info(f'Default KVS ID: {env.get("default_key_value_store_id")}')


if __name__ == '__main__':
    asyncio.run(main())

Platform detection

The Actor.is_at_home method returns True when the Actor is running on the Apify platform, and False when running locally. This is useful for branching behavior based on the environment, such as using different storage backends or skipping proxy configuration during local development.

Run on

import asyncio

from apify import Actor


async def main() -> None:
    async with Actor:
        if Actor.is_at_home():
            Actor.log.info('Running on the Apify platform')
        else:
            Actor.log.info('Running locally')


if __name__ == '__main__':
    asyncio.run(main())

Conclusion

This page has shown how to configure an Actor through the Configuration class or environment variables, which options you are most likely to set yourself, and how to inspect the runtime environment with Actor.get_env and Actor.is_at_home.

For the full list of configuration options, see the Configuration API reference. For a complete list of environment variables available on the platform, see the environment variables documentation.