Skip to content

Build and deploy a workflow project

Start a Python workflow from scratch or a published template, adapt it, and publish and run your first release.

Start with a small Python project or use an existing workflow as a template. You can edit and test the code locally, then publish your own workflow release and run it on a development cluster.

A release packages your code and dependencies so runners execute the version you tested. This guide takes you from project setup to your first job. For the underlying model, see Workflow releases.

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

Choose one of the two starting points below. Both create a local project; your first publication creates the workflow in your Tilebox organization.

Start from scratch

Create a project with a small HelloWorld task:

bash
tilebox workflow init ./my-workflow --name "My Workflow"
cd my-workflow

The command writes tilebox.workflow.toml, pyproject.toml, and runner.py, and runs uv sync to install dependencies and create uv.lock. You can edit runner.py directly while your workflow is small.

Start from a template

A template lets you start with working task code, dependencies, and release configuration from an existing workflow. Your copy becomes an independent project: publishing your changes creates your own workflow and leaves the original unchanged.

Browse publicly shared workflows, or omit --shared to browse your organization’s workflows:

bash
tilebox workflow list --shared

Choose a workflow with a published release. Replace <template-reference> below with its reference from the list:

bash
tilebox workflow init ./my-workflow \
  --template <template-reference> \
  --name "My Workflow"
cd my-workflow

This copies the latest published release into my-workflow, which must be a new or empty directory. Your project includes the template’s Python code, dependencies, and build configuration.

Look through the downloaded code and dependencies, then install them:

bash
uv sync

You can now adapt the tasks to your needs: change the area you process, use a different dataset, or write results to your own storage. Choose where to run your workflow in the next step.

Configure a deployment target

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

bash
tilebox cluster create "workflow-dev"
Output text
Slug               workflow-dev-<...>
Name               workflow-dev
Deletable          true

Append this target to tilebox.workflow.toml, replacing <cluster-slug> with the returned slug. Keep the existing workflow and build sections, especially when starting from a template.

tilebox.workflow.toml toml
[targets.dev]
clusters = ["<cluster-slug>"]

Build and publish the release

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

bash
tilebox workflow publish-release

Your first publication creates the workflow in Tilebox. Later publications add releases to that same workflow as you change the code.

Publishing creates an immutable release. It does not change what any cluster runs until you deploy it. If you cloned an existing project to continue work on a workflow that already exists, link the checkout before publishing.

Deploy to a development cluster

Deploy the release to the development target.

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

In a second terminal, start a release runner in an environment you control. Use the same cluster slug you added to the target, and leave the runner running while you submit jobs from the project terminal.

bash
tilebox runner start --cluster <cluster-slug> --debug

Run and inspect a job

From the project directory, use --workflow . to submit to your workflow. The dot tells the CLI to use the workflow remembered for this local project, so you do not need to copy its remote reference into every command.

If you started from scratch with the name above, run the generated HelloWorld task. Replace <cluster-slug> with your development cluster:

bash
tilebox job submit \
  --name my-workflow-test \
  --workflow . \
  --task my-workflow/HelloWorld \
  --version v0.1 \
  --cluster <cluster-slug> \
  --input '{"name":"Tilebox"}' \
  --wait
text
Job submitted: 019ef7a2-56b4-7a86-9c4d-52a1792b1e90

For a template project, use the task name, version, and inputs from its Python task definitions. Keep --workflow . to run the task from your own workflow, even if you kept the template’s task names.

Inspect the result before making the next change.

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

Next steps

Type to search…