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

# Build and deploy a workflow project

> Initialize a Python workflow project, publish a workflow release, and deploy it to a development cluster.

Use workflow releases when the code under test should match the code that runners execute. A release packages a Python workflow project, records the discovered task identifiers, and lets release runners load the deployed code from a cluster.

This guide summarizes the build and deploy path. For the underlying model, see [Workflow releases](https://docs-old.tilebox.com/workflows/concepts/workflow-releases.md) and [Release lifecycle](https://docs-old.tilebox.com/workflows/build-and-deploy/releases.md).

## Prerequisites

* You have installed the [Tilebox CLI](https://docs-old.tilebox.com/agents-and-ai-tools/tilebox-cli.md).
* `TILEBOX_API_KEY` is set in the shell where you run commands.
* `uv` is installed and available on `PATH`.

## Initialize the project

Create a project directory and initialize it as a Tilebox workflow project.

```bash theme={"system"}
mkdir my-workflow
cd my-workflow
tilebox workflow init --name "My Workflow"
```

The init command creates the Tilebox workflow, writes `tilebox.workflow.toml`, creates a minimal Python project with `runner.py`, adds the `tilebox` dependency, and runs `uv sync`. It aborts if `tilebox.workflow.toml`, `pyproject.toml`, `runner.py`, or `uv.lock` already exists in the current directory.

**my-workflow**

**pyproject.toml**

**uv.lock**

**tilebox.workflow\.toml**

**runner.py**

## Configure a deployment target

Create a logical cluster to deploy the workflow release to, enabling [release runners](https://docs-old.tilebox.com/workflows/concepts/runners.md#release-runners).

```bash theme={"system"}
tilebox cluster create "workflow-dev"
```

```text Output theme={"system"}
Slug               workflow-dev-<...>
Name               workflow-dev
Deletable          true
```

Add the returned cluster slug to `tilebox.workflow.toml` so deployment commands can refer to a logical environment instead of repeating cluster slugs.

```toml tilebox.workflow.toml theme={"system"}
[workflow]
slug = "my-workflow-<...>"
root = "."
runner = "runner:runner"

[build]
include = [
  "tilebox.workflow.toml",
  "pyproject.toml",
  "uv.lock",
  "runner.py",
]

[targets.dev]
clusters = ["workflow-dev-<...>"]
```

## Build and publish the release

Create a new release of the workflow and publish it to Tilebox.

```bash theme={"system"}
tilebox workflow publish-release
```

Publishing creates an immutable release. It does not change what any cluster runs until you deploy it.

> [!TIP]
>
> Build locally first when you want detailed validation output.
>
> `tilebox workflow build-release --debug`

## Deploy to a development cluster

Deploy the release to the development target.

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

Start a release runner in an environment you control.

```bash theme={"system"}
tilebox runner start --cluster workflow-dev-9xK2mQ4pL8nR7s --debug
```

## Run and inspect a job

Submit a task that matches one of the identifiers discovered from the release.

```bash theme={"system"}
tilebox job submit \
  --name my-workflow-test \
  --task my-workflow/HelloWorld \
  --version v0.1 \
  --cluster workflow-dev-9xK2mQ4pL8nR7s \
  --input '{"name":"Tilebox"}' \
  --wait
```

```text theme={"system"}
Job submitted: 019ef7a2-56b4-7a86-9c4d-52a1792b1e90
```

Inspect the result before making the next change.

```bash theme={"system"}
tilebox job logs <JOB_ID>
tilebox job spans <JOB_ID>
```

## Next steps

> [card] [Project structure](https://docs-old.tilebox.com/workflows/build-and-deploy/project-structure.md)
>
> Learn the details of Python workflow project layout.

> [card] [Deploy to your compute](https://docs-old.tilebox.com/guides/workflows/deploy-to-your-compute.md)
>
> Choose where release runners run and how clusters map to environments.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.