> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tilebox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```bash theme={"system"}
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`.

```bash theme={"system"}
tilebox workflow deploy-release --latest --cluster workflow-dev
```

For repeated deployments, define targets in the workflow configuration.

```toml theme={"system"}
[targets.dev]
clusters = ["workflow-dev"]

[targets.production]
clusters = ["workflow-prod"]
```

Then deploy by target name.

```bash theme={"system"}
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.

```bash theme={"system"}
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`](https://github.com/orgs/tilebox/packages/container/package/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.

```bash theme={"system"}
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`.

```bash theme={"system"}
kubectl create secret generic tilebox-runner \
  --from-literal=api-key="$TILEBOX_API_KEY"
```

Save this manifest as `runner-deployment.yaml`.

```yaml runner-deployment.yaml theme={"system"}
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.

```bash theme={"system"}
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.

```bash theme={"system"}
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, you can run multiple runner processes inside one container or shell session. Use `tilebox parallel` only for that case.

```bash theme={"system"}
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](/workflows/build-and-deploy/cluster-deployments) and [Runners](/workflows/concepts/runners).