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 the configuration options can be set via environment variables. The environment variables are prefixed with APIFY_, and the configuration options are in uppercase, with underscores as separators. See the Configuration API reference for the full list of configuration options.

This Actor run will not persist its local storages to the filesystem:

APIFY_PERSIST_STORAGE=0 apify run

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())

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.