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_KEYis set in the shell where you run commands.uvis installed and available onPATH.
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:
tilebox workflow init ./my-workflow --name "My Workflow"
cd my-workflowThe 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:
tilebox workflow list --sharedChoose a workflow with a published release. Replace <template-reference> below with its reference from the list:
tilebox workflow init ./my-workflow \
--template <template-reference> \
--name "My Workflow"
cd my-workflowThis 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:
uv syncYou 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.
tilebox cluster create "workflow-dev"Slug workflow-dev-<...>
Name workflow-dev
Deletable trueAppend 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.
[targets.dev]
clusters = ["<cluster-slug>"]Build and publish the release
Create a new release of the workflow and publish it to Tilebox.
tilebox workflow publish-releaseYour 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.
tilebox workflow deploy-release --latest --target devIn 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.
tilebox runner start --cluster <cluster-slug> --debugRun 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:
tilebox job submit \
--name my-workflow-test \
--workflow . \
--task my-workflow/HelloWorld \
--version v0.1 \
--cluster <cluster-slug> \
--input '{"name":"Tilebox"}' \
--waitJob submitted: 019ef7a2-56b4-7a86-9c4d-52a1792b1e90For 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.
tilebox job logs <JOB_ID>
tilebox job spans <JOB_ID>