Environment

A platform run describes itself through environment variables. This page lists what the platform injects, how the SDK exposes it, how to tune the SDK configuration, how browser crawlers reach the remote browser, and how to get an API client.

Environment and run metadata

Actor.getEnv()

getEnv() reads the environment and returns an object (TypeScript type ApifyEnv, a compatibility name). Missing values are null. It's available as Actor.getEnv() and on instances.

The object also has compatibility fields that Scrape.ly doesn't set (dedicatedCpus, fact, workflowKey, systemInfoIntervalMillis, disableOutdatedWarning, sdkLatestVersion, inputSecretsPrivateKeyFile, inputSecretsPrivateKeyPassphrase).

Variables the platform injects

These are set on every platform run container. Don't set them yourself.

Identity and storage

Authentication and API

Runtime

Pricing

Environment variables defined in your Actor's version settings or environmentVariables in the Actor config are added too. Secret inputs are decrypted on the host before the container starts; the platform doesn't provide the APIFY_INPUT_SECRETS_PRIVATE_KEY_* variables.

Convenience properties

These are static getters on Actor:

const msLeft = Actor.getRemainingTime();
if (msLeft !== undefined && msLeft < 30_000) {
    await Actor.exit('Stopping before the timeout');
}
const custom = Actor.getenv('MY_SETTING');

Actor.getRemainingTime() returns milliseconds until ACTOR_TIMEOUT_AT (never below 0), or undefined when there's no timeout. Actor.getenv(key) returns process.env[key]. Actor.isAtHome() is true on a platform run.

Web server and standby metadata

There are no dedicated getters for the web server. Read the values from the configuration:

const port = Actor.config.get('containerPort');   // ACTOR_WEB_SERVER_PORT, default 4321
const url = Actor.config.get('containerUrl');     // ACTOR_WEB_SERVER_URL
const standbyUrl = Actor.config.get('standbyUrl'); // ACTOR_STANDBY_URL
const isStandby = Actor.isStandby();               // metaOrigin === 'STANDBY'

The SDK doesn't start an HTTP server; your code listens on containerPort. See Standby mode.

Configuration

Configuration extends Crawlee's configuration with Scrape.ly fields. Actor.init() builds it from the environment; most Actors never touch it.

import { Actor } from 'scrapely';

const token = Actor.config.get('token');
Actor.config.set('persistStateIntervalMillis', 30_000);

To set values before the SDK reads them, pass configuration to Actor.init() or Actor.main() (a matching environment variable still takes precedence):

await Actor.main(async () => { /* ... */ }, {
    configuration: { persistStateIntervalMillis: 30_000 },
});

Scrape.ly fields and their environment variables:

An environment variable that is set wins over a value passed in configuration or set with set(); defaults apply last. When several variables map to one field, they carry the same value on the platform. Crawlers use the global configuration by default; pass Actor.config as the second constructor argument only if you created a separate Actor instance:

const crawler = new CheerioCrawler({ /* ... */ }, Actor.config);

Browsers and remote CDP

Where a browser runs depends on the Actor's Use Scrapely browser setting, which is off by default and applied per build. See Scrape.ly Browser.

Importing the SDK patches Crawlee's browser pool and the Playwright and Puppeteer launchers. The scrapely/actor-node* images also preload the patch through NODE_OPTIONS, so Actors that don't import the SDK are covered.

CDP_URL is set on every run, whatever the setting. setCdpUrl(url) overrides it and setCdpUrl(undefined) clears the override. Call it before the first browser launches, for example to point a local run at a CDP endpoint you host:

import { Actor, PlaywrightCrawler, setCdpUrl } from 'scrapely';

setCdpUrl('wss://browser.example.com/devtools?token=...');

const crawler = new PlaywrightCrawler({
    async requestHandler({ page }) {
        await Actor.pushData({ title: await page.title() });
    },
});

The Scrape.ly browser has its own exit IP and ignores your proxy URLs. Choose its location with createBrowserConfiguration().

Instance API and API client

Instance API

The class can be instantiated for code that expects an Actor object:

const actor = new Actor();
await actor.init();
const input = await actor.getInputOrThrow<{ url: string }>();
await actor.pushData({ url: input.url });
await actor.exit({ exit: false });

new Actor(options?) takes ConfigurationOptions. Without options it uses the global configuration. The first instance created becomes the default instance that the static methods use; Actor.getDefaultInstance() returns it.

Instances have the lifecycle, input, storage, status, proxy, browser, state, reboot, metamorph, abort, webhook, call, charging, getEnv(), isAtHome(), and isStandby() methods, plus actor.config and actor.apifyClient. These are static only: the run metadata getters, Actor.events, Actor.input, Actor.getenv(), Actor.getRemainingTime(), and Actor.utils.

API client

Actor.apifyClient and Actor.newClient() return an ApifyClient from scrapely-client, the Scrape.ly JavaScript API client. The name is kept so existing code works; it's the same class as ScrapelyClient. See JavaScript client for its full API.

const client = Actor.newClient();
const actorInfo = await client.actor('owner~name').get();

const other = Actor.newClient({ token: process.env.OTHER_TOKEN });

The run's client uses the internal API URL for requests and APIFY_API_PUBLIC_BASE_URL for public links such as getRecordPublicUrl(). On pay-per-event Actors it also charges for writes to the default dataset (see Default dataset item event).

ApifyClient, ApifyClientOptions, and ActorRun are re-exported from the SDK root.