Deploy to your compute

Run Tilebox workflow releases on compute environments you control by using clusters and release runners.

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.

Run the official runner container

Tilebox publishes a ready-to-run release runner at ghcr.io/tilebox/runner for Linux amd64 and arm64. The image starts tilebox runner start by default and includes the Tilebox CLI, uv, Python 3.12 through 3.14, Git, Git LFS, and build dependencies for common scientific and geospatial Python packages. Workflow code arrives through the releases deployed to the selected cluster, so you do not rebuild the image when a workflow changes.

Export an API key, then start the runner for your cluster.

export TILEBOX_API_KEY="<API_KEY>"

docker run --rm \
  --env TILEBOX_API_KEY \
  --env TILEBOX_CLUSTER=workflow-dev \
  ghcr.io/tilebox/runner:0.5.0

TILEBOX_API_KEY is required. TILEBOX_CLUSTER is optional; when omitted, the runner uses your default cluster. Provide credentials through your deployment system instead of including them in the image.

Use the official image directly when its runtime matches your workflow. Build a custom image from it when your code needs more operating system packages. The image does not include the NVIDIA CUDA toolkit, so CUDA extensions require a version-matched NVIDIA development image and GPU runtime.

Deploy the runner on Kubernetes

Run the image as a Kubernetes Deployment so the platform restarts the runner and lets you scale the number of processes. Store the API key in a Secret.

kubectl create secret generic tilebox-runner \
  --from-literal=api-key="$TILEBOX_API_KEY"

Save this manifest as runner-deployment.yaml.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: tilebox-runner
spec:
  replicas: 1
  selector:
    matchLabels:
      app: tilebox-runner
  template:
    metadata:
      labels:
        app: tilebox-runner
    spec:
      containers:
        - name: runner
          image: ghcr.io/tilebox/runner:0.5.0
          env:
            - name: TILEBOX_API_KEY
              valueFrom:
                secretKeyRef:
                  name: tilebox-runner
                  key: api-key
            - name: TILEBOX_CLUSTER
              value: workflow-dev

Apply the manifest.

kubectl apply -f runner-deployment.yaml

The same image can run as a long-lived process on container or virtual machine services such as Amazon ECS, Amazon EKS, Amazon EC2, Google Kubernetes Engine, or Google Compute Engine. Inject TILEBOX_API_KEY with the platform’s secret manager and set TILEBOX_CLUSTER in the container environment.

For a job-based container service that expects the process to exit, such as Cloud Run jobs, replace the default command with tilebox runner start --stop-when-idling. The runner processes available work, then exits when it becomes idle.

docker run --rm \
  --env TILEBOX_API_KEY \
  --env TILEBOX_CLUSTER=workflow-dev \
  ghcr.io/tilebox/runner:0.5.0 \
  tilebox runner start --stop-when-idling

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 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, use -n to run multiple independent release runners inside one CLI process.

tilebox runner start -n 3 --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:

The job was submitted to the expected cluster.
The workflow release is deployed to that cluster.
A release runner is running for that cluster.

For details, see Cluster deployments and Runners.