Skip to main content
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>

​
Next steps

Project structure

Learn the details of Python workflow project layout.

Deploy to your compute

Choose where release runners run and how clusters map to environments.