Run your first workflow

This guide runs a minimal workflow with a direct runner. It gives you the fastest path to the Tilebox Workflows execution model before publishing workflow releases or deploying to a cluster. Use this path when you are developing locally as a developer. If you want an agent to do the setup and iteration for you, start with Onboard your agent and then follow Iterate on workflow releases with agents.

Prerequisites

You have a Tilebox API key.
You have installed the Python SDK.

uv add tilebox
export TILEBOX_API_KEY="YOUR_TILEBOX_API_KEY"

Create a workflow file

Create a file named hello_workflow.py.

hello_workflow.py

from tilebox.workflows import Client, ExecutionContext, Runner, Task


class HelloWorkflow(Task):
    name: str

    def execute(self, context: ExecutionContext) -> None:
        context.logger.info("Running root task", name=self.name)
        context.submit_subtask(WriteGreeting(name=self.name))


class WriteGreeting(Task):
    name: str

    def execute(self, context: ExecutionContext) -> None:
        context.logger.info("Hello from Tilebox", name=self.name)


if __name__ == "__main__":
    client = Client()
    runner = Runner(tasks=[HelloWorkflow, WriteGreeting])

    job = client.jobs().submit(
        "hello-workflow",
        HelloWorkflow(name="Earth"),
    )
    print(f"Submitted job: {job.id}")

    runner.connect_to(client).run_all()

The root task submits one subtask. Tilebox tracks both tasks as part of the same job, and the direct runner executes all eligible work.

Run the workflow

Run the file locally.

uv run python hello_workflow.py

The script submits a job, starts a direct runner, executes the root task and subtask, and exits after the queued work is complete.

Inspect the job

Open the job in the Tilebox Console to inspect task state, logs, and the execution trace. For scripted inspection, use the jobs client or the Tilebox command-line tool:

tilebox job logs <job-id>
tilebox job spans <job-id>

Next steps

Tasks

Define task inputs, subtasks, dependencies, retries, and identifiers.

Build and deploy a workflow

Package the same kind of workflow code as a release and deploy it to a cluster.

Ingesting from common file formats Execute tasks in parallel

Tilebox Guides

Datasets

Workflows

Operations

Run your first workflow

Prerequisites

Create a workflow file

Run the workflow

Inspect the job

Next steps

Tasks

Build and deploy a workflow

​Prerequisites

​Create a workflow file

​Run the workflow

​Inspect the job

​Next steps

Tasks

Build and deploy a workflow

Prerequisites

Create a workflow file

Run the workflow

Inspect the job

Next steps