Skip to main content

Actor quickstart

In this guide you create an actor that pushes a few items to its dataset, run it locally, then push it to Lantfly and run it from the CLI and the API.

You need:

  • Node.js 22 or newer (for the Node.js actor and the CLI), or Python 3.10 or newer for a Python actor.
  • The Lantfly CLI, logged in with lantfly login --url https://lantfly.com.
  • Docker, only if you build the image yourself.
Packages coming soon

@lantfly/cli, @lantfly/actor-sdk and the Python package lantfly are not published to npm and PyPI yet. The steps below show how they work once they are. Until then npm install and pip install of these packages fail.

1. Scaffold the actor​

Terminal
lantfly init my-actor
cd my-actor

lantfly init creates:

my-actor/
my-actor/
  .actor/
    actor.json             # name, title, version, schemas, Dockerfile
    input_schema.json      # the input form and validation
    dataset_schema.json    # how the Console shows the results
  src/main.js              # your code
  storage/key_value_stores/default/INPUT.json   # input for local runs
  Dockerfile
  .dockerignore
  .gitignore
  package.json             # depends on @lantfly/actor-sdk
  README.md

The code reads the input and pushes count items:

src/main.js
import { Actor } from '@lantfly/actor-sdk';

await Actor.main(async () => {
  const { message = 'Hello from Lantfly', count = 3 } = await Actor.getInput();
  Actor.log.info(`Pushing ${count} items`);

  for (let index = 1; index <= count; index++) {
    await Actor.pushData({ index, message, at: new Date().toISOString() });
  }

  await Actor.setValue('OUTPUT', { message, count });
});

2. Run it locally​

Terminal
npm install
npm start

Without LANTFLY_IS_AT_HOME, the SDK runs in local mode: it reads storage/key_value_stores/default/INPUT.json and writes one file per item to storage/datasets/default/ and the OUTPUT record to storage/key_value_stores/default/OUTPUT.json.

Terminal
cat storage/datasets/default/000000001.json
tip

Delete storage/datasets/default/ between local runs: local datasets keep appending.

3. Push it to Lantfly​

Terminal
lantfly push

push reads .actor/actor.json, creates the actor under your account (or updates it), creates version 0.1, uploads the folder and streams the build log. When the build succeeds, the version points at the new image.

If you prefer to build from a public Git repository, run lantfly push --git-url https://github.com/you/my-actor. If builds are not available for your account, push prints the docker build and docker push commands to run yourself, then lantfly push --image-tag <tag>. See Builds and versions.

4. Run it on Lantfly​

From the CLI:

Terminal
lantfly call <username>~my-actor --input '{"count": 5}'

The CLI streams the log and prints the status and the number of items. Your username is shown by lantfly info.

From the API:

Start a run and wait up to 60 seconds
curl -X POST "https://lantfly.com/api/v3/actors/<username>~my-actor/runs" \
  -H "Authorization: Bearer $LANTFLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input": {"count": 5}, "wait_for_finish": 60}'
Read the items
curl "https://lantfly.com/api/v3/datasets/<default_dataset_id>/items?format=json&clean=1" \
  -H "Authorization: Bearer $LANTFLY_TOKEN"

In the Console (https://lantfly.com), the actor is under My actors. Open it to start a run from the form built from your input schema, and to see the log, the dataset and the key-value store of each run.

Next steps​