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 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.

Configure a deployment target

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

tilebox cluster create "workflow-dev"

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.

[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.

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>

Next steps