Actor environment

Every run starts your image in a fresh container with environment variables that tell it where its input and storages are, how to call the API and how to use the proxy. The Node.js and Python SDKs read them for you.

Environment variables

Set by the platform in every run:

Variable	Meaning
LANTFLY_IS_AT_HOME	1: the code runs on Lantfly. Unset on your machine, which puts the SDKs in local mode.
LANTFLY_API_BASE_URL	The API base URL, with /api/v3.
LANTFLY_TOKEN	The run token.
LANTFLY_USER_ID	The id of the account the run belongs to.
LANTFLY_ACTOR_ID	The actor's id.
LANTFLY_ACTOR_SLUG	The actor's username~name.
LANTFLY_ACTOR_RUN_ID	The run's id.
LANTFLY_DEFAULT_DATASET_ID	The run's default dataset.
LANTFLY_DEFAULT_KEY_VALUE_STORE_ID	The run's default key-value store.
LANTFLY_DEFAULT_REQUEST_QUEUE_ID	The run's default request queue.
LANTFLY_INPUT_KEY	The key of the input record in the default key-value store (INPUT).
LANTFLY_MEMORY_MBYTES	Memory of the run, in MB.
LANTFLY_TIMEOUT_AT	When the run times out (ISO 8601, UTC).
LANTFLY_PROXY_HOSTNAME, LANTFLY_PROXY_PORT, LANTFLY_PROXY_PASSWORD	The Lantfly proxy and your proxy password.
LANTFLY_MAX_PAID_DATASET_ITEMS	The caller's cap on paid dataset items, when set.
LANTFLY_MAX_TOTAL_CHARGE_USD	The caller's cap on pay-per-event and pay-per-result charges, when set.
ACTOR_WEB_SERVER_PORT	The port your actor listens on if it serves HTTP (default 4321). Used by Standby and live view.
ACTOR_WEB_SERVER_URL	The public URL of the run's web server, when live view is available. No token in it.
ACTOR_STARTED_AT, ACTOR_BUILD_ID, ACTOR_TASK_ID	When the run started, the build, and the task that started it (if any).

The same values are also set under ACTOR_* names (ACTOR_RUN_ID, ACTOR_DEFAULT_DATASET_ID, ACTOR_MEMORY_MBYTES, ACTOR_TIMEOUT_AT…) for libraries that read those names. Prefer the LANTFLY_* names in your own code.

Importing the Node.js SDK also sets CRAWLEE_MEMORY_MBYTES (from the run's memory) and CRAWLEE_STORAGE_DIR=/tmp/crawlee when they are not set.

Your own variables

Each version of an actor can carry its own environment variables, for example an API key of a service your actor calls. They are added to the container of every run of that version. Variables set by the platform always win over yours, and you cannot use the prefixes LANTFLY_, ACTOR_, CRAWLEE_ or other reserved prefixes.

Mark a variable as secret to keep its value out of the API and the Console: the value is masked as *** in run logs.

warning

Never put secrets in the input schema defaults, the README or the image. Use secret version variables, or ask callers for credentials in an input field with "isSecret": true.

The run token

LANTFLY_TOKEN is a token that exists only for this run. Send it as Authorization: Bearer $LANTFLY_TOKEN to LANTFLY_API_BASE_URL. The SDKs do this for you.

The run token can:

Call	Endpoints
Read its own run	GET /api/v3/runs/{run}, GET /api/v3/runs/{run}/log
Set the status message	PATCH /api/v3/runs/{run} with status_message, is_status_message_terminal
Report pay-per-event charges	POST /api/v3/runs/{run}/charge with event_name, count
Metamorph into another actor	POST /api/v3/runs/{run}/metamorph with target_actor_id, input, build
Read and write the run's default storages	the run's default dataset, key-value store and request queue
Open named storages of the account	POST /api/v3/datasets, POST /api/v3/key-value-stores with a name (get or create), then read and write them

Anything else answers 403 insufficient_permissions, and unnamed storages of other runs answer 404 not_found. The run token stops working 300 seconds after the run ends. If your actor must start other actors or manage resources, ask the caller for an API token in a secret input field or a secret version variable.

When the run belongs to an organization, the run token acts for that organization.

Calls from your actor

Set the status message from a shell script in the container

curl -X PATCH "$LANTFLY_API_BASE_URL/runs/$LANTFLY_ACTOR_RUN_ID" \
  -H "Authorization: Bearer $LANTFLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status_message": "Crawled 120 pages"}'

Push items

curl -X POST "$LANTFLY_API_BASE_URL/datasets/$LANTFLY_DEFAULT_DATASET_ID/items" \
  -H "Authorization: Bearer $LANTFLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"url": "https://example.com", "title": "Example"}]'

Write calls accept an Idempotency-Key header, so a retry after a lost answer is not applied twice. See Idempotency.

Resources and limits

Resource	Value
Memory	The run's memory_mb option (default: the actor's default options). At least 128 MB.
CPU	One CPU per 4 GB of memory, at least a quarter of a CPU.
Timeout	The run's timeout_secs option. LANTFLY_TIMEOUT_AT says when it ends.
User	The container runs as uid 1000, without new privileges.
Disk	Limited. Write temporary files to /tmp; the working directory may not be writable.

What happens at the end:

• Timeout or abort. The container gets SIGTERM, then about 10 seconds before it is killed. The SDKs flush buffered items and write OUTPUT in that time.
• Out of memory. The run fails with out of memory. Give it more memory or lower the concurrency.
• Exit code. 0 is a success; any other code fails the run.

Secrets (the run token, your proxy password, secret version variables) are masked as *** in the run log.

Network

The actor can reach the public internet directly or through the Lantfly proxy. Do not rely on reaching private or internal network addresses. The proxy URL contains your proxy password: never log it or put it in results.

Local runs

On your machine nothing of this is set. The SDKs then:

• read the input from ./storage/key_value_stores/default/INPUT.json;
• write datasets and records under ./storage (or LANTFLY_LOCAL_STORAGE_DIR);
• skip charges and status messages;
• use no proxy, unless you set LANTFLY_PROXY_URL to a plain upstream proxy ({session} in it becomes the session id).

To test the platform behavior locally, run the image with Docker and mount a storage folder:

Terminal

docker build -t my-actor .
docker run --rm --user 1000:1000 -v "$PWD/storage:/app/storage" my-actor