Builds and versions

A version of an actor (0.1, 1.0, 1.2…) points at one image tag and carries its own input schema, dataset schema, output schema, changelog, environment variables and Standby settings. One version is the default: runs use it unless they ask for another.

A build turns source code into an image tag. A successful build adds or updates its version and, by default, makes it the default version.

Three ways to get an image

Way	When	How
Upload the folder	Your actor folder has its Dockerfile	lantfly push
Build from Git	The code is in a public HTTPS Git repository	lantfly push --git-url …, the Console, or POST /api/v3/actors/{actor}/builds
Build it yourself	You build and push the image with Docker	lantfly push --no-upload, then lantfly push --image-tag <tag>

note

Builds on Lantfly may not be enabled for every account. When they are not, lantfly push says so and prints the docker build and docker push commands to run instead.

Upload the folder

Terminal

lantfly push

The CLI packs the actor folder into a .tar.gz, uploads it and streams the build log until the build ends. It exits non-zero when the build fails.

• Left out of the archive: what .gitignore and .dockerignore list, plus .git/, node_modules/, storage/, .env and .env.* (not .env.example), *.log and symlinks. The Dockerfile and .actor/ always go.
• The archive must stay under 50 MB compressed.
• The Dockerfile must be inside the folder. For a Dockerfile that builds from a parent folder (a monorepo), build from Git.

Build from Git

Terminal

lantfly push --git-url https://github.com/you/my-actor --git-ref main
lantfly push --build    # use the folder's origin remote

Or with the API:

Build version 1.0 from Git

curl -X POST "https://lantfly.com/api/v3/actors/<username>~my-actor/builds" \
  -H "Authorization: Bearer $LANTFLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.0",
    "git_url": "https://github.com/you/my-actor",
    "git_ref": "main",
    "dockerfile": "Dockerfile",
    "context": ".",
    "make_default": true
  }'

Field	Default	Meaning
version	required	The version to build, as major.minor.
git_url	required	A public HTTPS repository. The CLI turns SSH remotes into HTTPS.
git_ref	optional	Branch, tag or commit.
dockerfile	Dockerfile	Path of the Dockerfile in the repository.
context	.	Build context in the repository.
make_default	true	Make the version the default when the build succeeds.

Only one build of an actor runs at a time: a second request answers 422. Symlinks that point outside the repository are refused.

Build it yourself

Terminal

lantfly push --no-upload
# prints:
#   docker build -t <image>:<tag> .
#   docker push <image>:<tag>
lantfly push --image-tag <tag>

--image-tag points the version at a tag that already exists and never uploads anything. Your image must be in your own image repository (lantfly/<namespace>/<name>, where your namespace comes from your account); the API refuses other images with 422.

Follow builds

Task	CLI	API
List builds	lantfly builds ls <actor>	GET /api/v3/actors/{actor}/builds
Read a build log	lantfly builds log <actor> <buildId> --follow	GET /api/v3/actors/{actor}/builds/{build}/log?from=<offset>
Abort a build		POST /api/v3/actors/{actor}/builds/{build}/abort

The build log is paged like the run log: each call returns { chunk, offset, finished }; call again with from set to the returned offset until finished is true.

Versions

Task	API
List versions	GET /api/v3/actors/{actor}/versions
Add a version	POST /api/v3/actors/{actor}/versions with version, image_tag and the version fields below
Change a version	PATCH /api/v3/actors/{actor}/versions/{version}
Delete a version	DELETE /api/v3/actors/{actor}/versions/{version} (not the default version: 422)

Version fields:

Field	Meaning
image_tag	The image tag the version runs.
changelog	What changed, shown on the actor's page.
input_schema, dataset_schema, output_schema	The schemas of this version (see Actor definition).
env_vars	Environment variables of this version (below).
make_default	true makes this the default version.
standby	Actor Standby settings, or null to turn it off.

Make version 1.0 the default

curl -X PATCH "https://lantfly.com/api/v3/actors/<username>~my-actor/versions/1.0" \
  -H "Authorization: Bearer $LANTFLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"make_default": true}'

Choose a version for a run

Runs use the default version. Pass build in the run options to pick another one, by version number or image tag:

Run version 0.2

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": {}, "options": {"build": "0.2"}}'

latest or no build means the default version. An unknown build answers 422. With the CLI: lantfly call <actor> --build 0.2.

Environment variables

Set the version's environment variables

curl -X PATCH "https://lantfly.com/api/v3/actors/<username>~my-actor/versions/1.0" \
  -H "Authorization: Bearer $LANTFLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "env_vars": [
      { "name": "LOG_LEVEL", "value": "debug" },
      { "name": "SERVICE_API_KEY", "value": "sk-…", "is_secret": true }
    ]
  }'

• env_vars replaces the whole list.
• At most 100 variables; each value at most 50 KB.
• Names match ^[A-Za-z_][A-Za-z0-9_]*$ and may not start with LANTFLY_, ACTOR_, CRAWLEE_ or other reserved prefixes.
• The API never returns secret values: they come back as "value": null. Send a secret back with "value": null to keep its value.
• Only people who can change the actor see the list.
• Variables of the platform always win, and secret values are masked as *** in run logs.

A run uses the variables of the version it runs. After a metamorph, the target actor's version variables apply.