Skip to main content
Tilebox manages workflow state, releases, deployments, jobs, logs, and traces. Your compute environment runs the runner process that executes the work. This lets workflows run on local machines, cloud virtual machines, Kubernetes clusters, on-premises systems, or controlled customer infrastructure.

​
Choose a cluster for the environment

A cluster is the routing boundary for jobs and runners. Jobs submitted to a cluster can only be claimed by runners connected to the same cluster. Use separate clusters for environments that should not run the same code by accident, such as development and production-like compute. 
tilebox cluster create "workflow-dev"
tilebox cluster create "workflow-prod"

​
Deploy a release to the cluster

Deploy a published workflow release to the cluster or to a target defined in tilebox.workflow.toml. 
tilebox workflow deploy-release --latest --cluster workflow-dev
For repeated deployments, define targets in the workflow configuration. 
[targets.dev]
clusters = ["workflow-dev"]

[targets.production]
clusters = ["workflow-prod"]
Then deploy by target name. 
tilebox workflow deploy-release --latest --target dev

​
Start release runners where the work should run

Start one or more release runners in the environment that has the required network access, credentials, hardware, and data access. 
tilebox runner start --cluster workflow-dev --debug
The runner watches its cluster, downloads missing release artifacts, starts the workflow runtime, and advertises the tasks it can execute. Updating a deployment changes what the runner can execute without rebuilding the runner process.

​
Bundle the release runner in a container

For cloud or Kubernetes deployments, package the release runner into a small container image. The image only needs Python, uv, the Tilebox command-line tool, and any system dependencies your workflow runtime needs. The workflow code itself comes from the deployed workflow release.
Dockerfile
FROM python:3.13-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

# Install system dependencies.
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates curl git git-lfs openssh-client \
    && rm -rf /var/lib/apt/lists/* \
    && apt-get clean

RUN curl -fsSL https://install.tilebox.com/cli.sh | TILEBOX_INSTALL_DIR=/usr/local/bin TILEBOX_NO_INSTALL_COMPLETIONS=1 sh

# Required at runtime: set TILEBOX_CLUSTER to a valid cluster slug and
# TILEBOX_API_KEY to an API key that can read deployments and claim tasks.
ENV TILEBOX_CLUSTER=""
ENV TILEBOX_API_KEY=""

CMD ["tilebox", "runner", "start"]
Build and publish this image with your normal container workflow. At runtime, provide TILEBOX_CLUSTER and TILEBOX_API_KEY through your deployment system rather than baking secrets into the image. In Kubernetes, run the image as a Deployment and store TILEBOX_API_KEY in a Secret. Set TILEBOX_CLUSTER through the pod environment and scale replicas to increase runner concurrency. In Google Cloud, run the same image on Cloud Run jobs, GKE, or Compute Engine depending on your workload constraints. In AWS, run it on ECS, EKS, or EC2 and inject the API key through your secret manager or task definition.

​
Scale runner processes

Scale the number of runner containers or virtual machine instances when you want more parallelism. In Kubernetes, increase the Deployment replica count. In GCP or AWS, use the scaling controls of the service that runs the container, such as Cloud Run, GKE, ECS, EKS, or an auto-scaling VM group. Each runner process connects to the same cluster and claims compatible tasks independently. As an alternative for local testing or constrained environments, you can run multiple runner processes inside one container or shell session. Use tilebox parallel only for that case. 
tilebox parallel -n 4 -- tilebox runner start --cluster workflow-dev
Tilebox does not require the runner process to run in Tilebox-managed infrastructure. Use the process manager, scheduler, or container platform that fits your compute environment.

​
Verify cluster alignment

If a job stays queued, check that these three values match:
  1. The job was submitted to the expected cluster.
  2. The workflow release is deployed to that cluster.
  3. A release runner is running for that cluster.
For details, see Cluster deployments and Runners.