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"

Copy

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.

• Directorymy-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"

Copy

Output

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

Copy

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

Copy

Build and publish the release

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

tilebox workflow publish-release

Copy

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

Copy

Start a release runner in an environment you control.

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

Copy

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

Copy

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

Copy

Inspect the result before making the next change.

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

Copy

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.