Build and deploy a workflow project

Use workflow releases when the code under test should match the code that runners execute. A release packages a Python workflow project, records the discovered task identifiers, and lets release runners load the deployed code from a cluster. This guide summarizes the build and deploy path. For the underlying model, see Workflow releases and Release lifecycle.

Prerequisites

You have installed the Tilebox CLI.
TILEBOX_API_KEY is set in the shell where you run commands.
uv is installed and available on PATH.

Initialize the project

Create a project directory and initialize it as a Tilebox workflow project.

mkdir my-workflow
cd my-workflow
tilebox workflow init --name "My Workflow"

The init command creates the Tilebox workflow, writes tilebox.workflow.toml, creates a minimal Python project with runner.py, adds the tilebox dependency, and runs uv sync. It aborts if tilebox.workflow.toml, pyproject.toml, runner.py, or uv.lock already exists in the current directory.

my-workflow

pyproject.toml

uv.lock

tilebox.workflow.toml

runner.py

Configure a deployment target

Create a logical cluster to deploy the workflow release to, enabling release runners.

tilebox cluster create "workflow-dev"

Output

Slug               workflow-dev-<...>
Name               workflow-dev
Deletable          true

Add the returned cluster slug to tilebox.workflow.toml so deployment commands can refer to a logical environment instead of repeating cluster slugs.

tilebox.workflow.toml

[workflow]
slug = "my-workflow-<...>"
root = "."
runner = "runner:runner"

[build]
include = [
  "tilebox.workflow.toml",
  "pyproject.toml",
  "uv.lock",
  "runner.py",
]

[targets.dev]
clusters = ["workflow-dev-<...>"]

Build and publish the release

Create a new release of the workflow and publish it to Tilebox.

tilebox workflow publish-release

Publishing creates an immutable release. It does not change what any cluster runs until you deploy it.

Build locally first when you want detailed validation output.tilebox workflow build-release --debug

Deploy to a development cluster

Deploy the release to the development target.

tilebox workflow deploy-release --latest --target dev

Start a release runner in an environment you control.

tilebox runner start --cluster workflow-dev-9xK2mQ4pL8nR7s --debug

Run and inspect a job

Submit a task that matches one of the identifiers discovered from the release.

tilebox job submit \
  --name my-workflow-test \
  --task my-workflow/HelloWorld \
  --version v0.1 \
  --cluster workflow-dev-9xK2mQ4pL8nR7s \
  --input '{"name":"Tilebox"}' \
  --wait

Job submitted: 019ef7a2-56b4-7a86-9c4d-52a1792b1e90

Inspect the result before making the next change.

tilebox job logs <JOB_ID>
tilebox job spans <JOB_ID>

Tilebox Guides

Datasets

Workflows

Operations

Build and deploy a workflow project

Prerequisites

Initialize the project

Configure a deployment target

Build and publish the release

Deploy to a development cluster

Run and inspect a job

Next steps

Project structure

Deploy to your compute

​Prerequisites

​Initialize the project

​Configure a deployment target

​Build and publish the release

​Deploy to a development cluster

​Run and inspect a job

​Next steps

Project structure

Deploy to your compute

Prerequisites

Initialize the project

Configure a deployment target

Build and publish the release

Deploy to a development cluster

Run and inspect a job

Next steps