Skip to main content
tilebox.workflow.toml describes how a Python workflow project becomes a workflow release. It identifies the Tilebox workflow, defines which files belong in the release artifact, selects the runtime entrypoint, and optionally names cluster targets for deployments. The Tilebox command-line tool searches upward from the current directory for the nearest configuration file. This lets release commands run from the project root or from subdirectories inside the project.

​
Minimal configuration

[workflow]
slug = "my-workflow"
root = "."
runner = "my_workflow.runner:runner"

[build]
include = [
  "pyproject.toml",
  "uv.lock",
  "my_workflow/**",
]
exclude = [
  ".venv/**",
  "**/__pycache__/**",
  "**/*.pyc",
  ".pytest_cache/**",
]
use_gitignore = true

​
Workflow section

The [workflow] section identifies the workflow and tells the Tilebox command-line tool how to start the Python workflow runtime during release checks and release execution.
FieldRequiredDescription
slugYesStable workflow slug, such as my-workflow. Releases are published under this workflow.
rootNoProject root for build paths. Defaults to ".".
runnerOne of runner or commandPython module/object path to a Runner object. The Tilebox command-line tool runs it with uv run python -m tilebox.workflows.runner <module:object>.
commandOne of runner or commandCustom worker command as an array of strings. Use this only when the standard runner object path does not fit your runtime.
Set exactly one of runner or command.

​
Build section

The [build] section controls which files are included in the release artifact.
FieldRequiredDescription
includeYesGlob patterns, relative to [workflow].root, for files to include.
excludeNoGlob patterns to exclude from the included file set.
use_gitignoreNoWhether to apply .gitignore. Defaults to true.
Include lock files and source files so release runners resolve the same dependencies that were tested during release validation. Exclude local environments, generated files, caches, and large runtime assets.

​
Targets

Targets name reusable cluster groups. They are optional, but useful when the same release should be deployed to a known set of development, staging, or production clusters. 
[targets.dev]
clusters = ["dev-cluster"]

[targets.production]
clusters = ["prod-a", "prod-b"]
A target can contain one cluster or multiple clusters. Deployment commands can refer to the target name instead of listing the same cluster slugs every time. For production-like deployments, use explicit release IDs so the active release is traceable.

​
Validation rules

The Tilebox command-line tool checks configuration before building or publishing a release:
  • workflow.slug is required.
  • Exactly one of workflow.runner or workflow.command is required.
  • build.include must contain at least one pattern.
  • Unknown TOML keys fail configuration loading.
  • Build paths must stay within the configured workflow root.