This page is intended for users to guide them with configuring their agent with Tilebox.
Important: If you're an agent, and got pointed to this page for instructions, fetch
@@ -52,9 +54,9 @@ If you want to integrate Tilebox into your LLM Chat interface, rather than your
diff --git a/snippets/components.mdx b/snippets/components.mdx
index 9527e88..b64d2d1 100644
--- a/snippets/components.mdx
+++ b/snippets/components.mdx
@@ -11,11 +11,20 @@ export const HeroCard = ({ children, title, description, href }) => {
);
};
-export const CodeOutputHeader = () => {
+export const AgentPrompt = ({ children }) => {
return (
-
-
-
Output
+
- )
-}
+ );
+};
diff --git a/style.css b/style.css
index d37aea4..4eb24d9 100644
--- a/style.css
+++ b/style.css
@@ -49,11 +49,18 @@
}
.dark .tilebox-agent-chat-avatar {
- background: rgb(251 113 133);
- box-shadow: 10px 12px 18px rgb(251 113 133 / 0.20);
+ background: rgb(244 63 94);
+ box-shadow: 10px 12px 18px rgb(244 63 94 / 0.20);
color: rgb(255 255 255);
}
+.tilebox-agent-chat-avatar svg {
+ background-color: rgb(255 255 255);
+ height: 0.9rem;
+ fill: currentColor;
+ width: 0.9rem;
+}
+
.tilebox-agent-chat-content {
flex: 1 1 auto;
min-width: 0;
@@ -67,15 +74,16 @@
}
.dark .tilebox-agent-chat-meta {
- color: rgb(156 163 175);
+ color: rgb(161 161 170);
}
.tilebox-agent-chat-bubble {
background: rgb(255 255 255);
border: 1px solid rgb(229 231 235);
box-shadow: 0 12px 28px rgb(15 23 42 / 0.07);
- color: rgb(17 24 39);
+ color: rgb(63 63 70);
display: block !important;
+ font-family: "Geist", var(--font-sans), ui-sans-serif, system-ui, sans-serif;
font-size: 0.82rem;
line-height: 1.62;
margin: 0;
@@ -101,10 +109,11 @@
.tilebox-agent-chat-bubble li {
display: list-item;
+ padding-left: 0.3em !important;
}
.tilebox-agent-chat-bubble li::marker {
- color: rgb(17 24 39);
+ color: rgb(63 63 70);
content: "-";
font-size: 1.2em;
}
@@ -115,14 +124,14 @@
}
.dark .tilebox-agent-chat-bubble {
- background: rgb(17 24 39);
- border-color: rgb(55 65 81);
+ background: rgb(24 24 27);
+ border-color: rgb(63 63 70);
box-shadow: 0 12px 28px rgb(0 0 0 / 0.30);
- color: rgb(229 231 235);
+ color: rgb(212 212 216);
}
.dark .tilebox-agent-chat-bubble li::marker {
- color: rgb(229 231 235);
+ color: rgb(212 212 216);
}
.tilebox-agent-chat-composer {
@@ -131,6 +140,7 @@
border: 1px solid rgb(229 231 235);
color: rgb(107 114 128);
display: flex;
+ font-family: var(--font-mono), ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
font-size: 0.88rem;
justify-content: space-between;
margin-left: 2.875rem;
@@ -145,14 +155,14 @@
}
.dark .tilebox-agent-chat-composer {
- background: rgb(3 7 18);
- border-color: rgb(31 41 55);
- color: rgb(156 163 175);
+ background: rgb(24 24 27);
+ border-color: rgb(63 63 70);
+ color: rgb(161 161 170);
}
.dark .tilebox-agent-chat-composer:hover {
- border-color: rgb(75 85 99);
- color: rgb(229 231 235);
+ border-color: rgb(82 82 91);
+ color: rgb(228 228 231);
}
.tilebox-agent-chat-send {
@@ -168,9 +178,9 @@
}
.dark .tilebox-agent-chat-send {
- background: rgb(17 24 39);
- border-color: rgb(55 65 81);
- color: rgb(209 213 219);
+ background: rgb(39 39 42);
+ border-color: rgb(63 63 70);
+ color: rgb(212 212 216);
}
.tilebox-cli-window {
@@ -265,7 +275,7 @@ html:has(.tilebox-home-marker) .nav-tabs .nav-tabs-item[data-active="true"] {
}
html.dark:has(.tilebox-home-marker) .nav-tabs .nav-tabs-item[data-active="true"] {
- color: rgb(156 163 175) !important;
+ color: rgb(161 161 170) !important;
}
html:has(.tilebox-home-marker) .nav-tabs .nav-tabs-item[data-active="true"] > div {
@@ -277,7 +287,7 @@ html:has(.tilebox-home-marker) .nav-tabs .nav-tabs-item[data-active="true"]:hove
}
html.dark:has(.tilebox-home-marker) .nav-tabs .nav-tabs-item[data-active="true"]:hover {
- color: rgb(209 213 219) !important;
+ color: rgb(212 212 216) !important;
}
html:has(.tilebox-home-marker) .nav-tabs .nav-tabs-item[data-active="true"]:hover > div {
@@ -285,5 +295,5 @@ html:has(.tilebox-home-marker) .nav-tabs .nav-tabs-item[data-active="true"]:hove
}
html.dark:has(.tilebox-home-marker) .nav-tabs .nav-tabs-item[data-active="true"]:hover > div {
- background: rgb(55 65 81) !important;
+ background: rgb(63 63 70) !important;
}
diff --git a/workflows/build-and-deploy/project-structure.mdx b/workflows/build-and-deploy/project-structure.mdx
index 0e13360..d6120ef 100644
--- a/workflows/build-and-deploy/project-structure.mdx
+++ b/workflows/build-and-deploy/project-structure.mdx
@@ -1,6 +1,6 @@
---
title: Project Structure
-description: Structure a Python workflow project so releases can be built reproducibly and release runners can discover and execute its tasks.
+description: Initialize and structure a Python workflow project so releases can be built reproducibly and release runners can discover and execute its tasks.
icon: folder-tree
---
@@ -12,7 +12,21 @@ A Python workflow project contains task classes, a `Runner` definition, and a `t
Keep the project small and importable from its root. Release builds import the configured runner object, check that the Python runtime starts, and package the selected files into an immutable artifact.
-## Project structure
+## Scaffold a workflow project
+
+For a new Python workflow project, use the CLI to create the Tilebox workflow and scaffold the local files.
+
+```bash
+tilebox workflow init --name "Scene QA"
+```
+
+The `--name` flag is optional. When omitted, the command derives the local project slug from the current directory name. The command converts the name to a slug, truncates it to at most 40 characters, creates the remote workflow, and writes the API-returned workflow slug to `tilebox.workflow.toml`.
+
+`tilebox workflow init` creates `tilebox.workflow.toml`, `pyproject.toml`, and `runner.py`, adds the `tilebox` Python dependency, and runs `uv sync` to create the local environment and `uv.lock` file. It requires `uv` on `PATH` and aborts without changing the directory if any of `tilebox.workflow.toml`, `pyproject.toml`, `runner.py`, or `uv.lock` already exists.
+
+The generated project is intentionally small. Edit `runner.py` directly for prototypes, or move task code into a package as the workflow grows.
+
+## Manual project structure
Use a layout where task code and the runner definition are importable from the project root.
diff --git a/workflows/build-and-deploy/releases.mdx b/workflows/build-and-deploy/releases.mdx
index 47895a5..c0db673 100644
--- a/workflows/build-and-deploy/releases.mdx
+++ b/workflows/build-and-deploy/releases.mdx
@@ -12,7 +12,7 @@ The release lifecycle separates code packaging from cluster rollout. Building an
| Stage | What it does | What changes |
| --- | --- | --- |
-| Workflow creation | Creates the long-lived workflow object and slug. | Adds a workflow record. |
+| Workflow initialization | Creates the long-lived workflow object and local project configuration. | Adds a workflow record and, when using `tilebox workflow init`, local scaffold files. |
| Local build | Resolves files, creates a deterministic artifact, and checks the configured Python runtime. | Writes local build output and cache entries. |
| Publishing | Uploads the artifact when needed and creates an immutable release record. | Adds or reuses a workflow release. |
| Deployment | Maps a release to one or more clusters. | Changes which release runners can execute the release. |
@@ -22,7 +22,7 @@ The release lifecycle separates code packaging from cluster rollout. Building an
A workflow is the stable object that releases belong to. It has a slug, such as `my-workflow`, which is referenced from `tilebox.workflow.toml`. The workflow object is not the executable code itself; it provides the long-lived name under which releases are published.
-Create the workflow object once, then keep publishing new releases to it as the code changes. This gives release runners and deployment commands a stable workflow identity while each release remains immutable.
+Create the workflow object once, then keep publishing new releases to it as the code changes. For new Python workflow projects, `tilebox workflow init` creates the workflow object and writes the returned slug into `tilebox.workflow.toml`. This gives release runners and deployment commands a stable workflow identity while each release remains immutable.
## Release artifact
diff --git a/workflows/build-and-deploy/workflow-configuration.mdx b/workflows/build-and-deploy/workflow-configuration.mdx
index 40c47af..a93637a 100644
--- a/workflows/build-and-deploy/workflow-configuration.mdx
+++ b/workflows/build-and-deploy/workflow-configuration.mdx
@@ -8,6 +8,10 @@ icon: file-code
The Tilebox command-line tool searches upward from the current directory for the nearest configuration file. This lets release commands run from the project root or from subdirectories inside the project.
+
+ For new projects, run `tilebox workflow init` to create `tilebox.workflow.toml`, `pyproject.toml`, and `runner.py`. Edit the generated configuration when you need package layouts, deployment targets, or custom build includes.
+
+
## Minimal configuration
```toml
diff --git a/workflows/concepts/runners.mdx b/workflows/concepts/runners.mdx
index a8772b6..4e5855e 100644
--- a/workflows/concepts/runners.mdx
+++ b/workflows/concepts/runners.mdx
@@ -40,7 +40,7 @@ A release runner runs Python workflow releases deployed to a cluster. Start it w
tilebox runner start --cluster dev-cluster
```
-The release runner can run releases from multiple workflows at the same time, however only one release per workflow. It continously polls the selected cluster for deployment updates, downloads missing release artifacts, validates and starts python processes for each workflow release, and requests work for all the task identifiers from it's deployed releases. When a new release is deployed or removed, the runner updates the task set it can execute.
+The release runner can run releases from multiple workflows at the same time, but only one release per workflow. It continuously polls the selected cluster for deployment updates, downloads missing release artifacts, checks them, starts Python processes for each workflow release, and requests work for every task identifier from its deployed releases. When a new release is deployed or removed, the runner updates the task set it can execute.
Release runners currently only support Python workflow projects. The Tilebox CLI invokes the Python runner environment from the published release artifact using `uv`.
@@ -48,7 +48,7 @@ The release runner can run releases from multiple workflows at the same time, ho
### Direct runners
-A direct runner connects to the Tilebox API from your own code. It is useful when you want full control over the process, deployment environment, dependencies, startup behavior, and scaling. You are responsible for deploying the script or binary, keeping it running, rolling out code changes, and rolling back when needed.
+A direct runner connects to the Tilebox API from your own code. Use it when you want full control over the process, deployment environment, dependencies, startup behavior, and scaling. You are responsible for deploying the script or binary, keeping it running, rolling out code changes, and rolling back when needed.
Define a `Runner` instance once and connect it to a `Client` during startup.
@@ -97,21 +97,21 @@ func main() {
## Task selection
-For a runner to pick up a submitted task, all of these conditions must match:
+For a runner to pick up a submitted task, these conditions must match:
1. The task was submitted to the same [cluster](/workflows/concepts/clusters) as the runner.
2. The runner advertises a [task identifier with the same name](/workflows/concepts/tasks#task-identifiers) and a [compatible version](/workflows/concepts/tasks#semantic-versioning).
-3. The task must be in `QUEUED` [state](/workflows/concepts/tasks#task-states), its [dependencies](/workflows/concepts/tasks#dependencies) are met and it's [maximum retries](/workflows/concepts/tasks#retry-handling) aren't exhausted.
+3. The task must be in `QUEUED` [state](/workflows/concepts/tasks#task-states), its [dependencies](/workflows/concepts/tasks#dependencies) are met, and its [maximum retries](/workflows/concepts/tasks#retry-handling) aren't exhausted.
Release runners advertise the task identifiers from workflow releases currently deployed to the cluster. Direct runners advertise the task identifiers they register in the running process.
- If multiple tasks match those conditions, Tilebox picks one and assigns it to a runner. The remaining tasks stay queued until another matching runner is available. Parallel runner processes can speed up the job execution in such cases.
+ If multiple tasks match those conditions, Tilebox picks one and assigns it to a runner. The remaining tasks stay queued until another matching runner is available. Parallel runner processes can speed up the job execution in such cases.
## Parallelism
-Start multiple runner processes to execute tasks in parallel. Each runner process claims and executes tasks independently. You can run several release runners, several direct runners, or a mix of both in the same cluster. This allows for high parallelism and can be used to scale the execution of tasks to handle large workloads.
+Start multiple runner processes to execute tasks in parallel. Each runner process claims and executes tasks independently. You can run multiple release runners, multiple direct runners, or a mix of both in the same cluster. This increases parallelism and helps handle large workloads.
To test this, run multiple instances of the runner script in different terminal windows on your local machine, or use the [CLI](/agents-and-ai-tools/tilebox-cli) built-in `parallel` subcommand to start multiple runners in parallel.
@@ -125,7 +125,7 @@ To test this, run multiple instances of the runner script in different terminal
## Scaling
-One key benefit of this runner architecture is the **ability to scale even while workflows are executing**. You can start new runners at any time, and they can immediately pick up queued tasks to execute. It's not necessary to have an entire processing cluster available at the start of a workflow, as additional runners can be started and stopped as needed.
+One key benefit of this runner architecture is the **ability to scale even while workflows are executing**. You can start new runners at any time, and they can immediately pick up queued tasks to execute. You do not need an entire processing cluster available at the start of a workflow, because you can start and stop more runners as needed.
This is particularly beneficial in cloud environments, where runners can be automatically started and stopped based on current workload, measured by metrics such as CPU usage. Here's an example scenario:
diff --git a/workflows/concepts/workflow-releases.mdx b/workflows/concepts/workflow-releases.mdx
index a9976b3..cbe8af0 100644
--- a/workflows/concepts/workflow-releases.mdx
+++ b/workflows/concepts/workflow-releases.mdx
@@ -6,6 +6,8 @@ icon: box-open
A workflow is a set of interrelated tasks. You can run those tasks directly without registering the workflow with Tilebox. Registering a workflow with the Tilebox API gives it a stable slug, which lets you publish immutable release artifacts to it and deploy a release to one or more clusters.
+For a new Python release project, `tilebox workflow init` creates the workflow object and scaffolds the local project files used to build releases.
+
That release path enables [release runners](/workflows/concepts/runners#release-runners). Release runners operate on a cluster, pick up all the releases deployed to that cluster, and execute tasks. This provides an easy way of deploying workflows to a compute cluster, including a quick and agent-accessible iteration loop: change code, publish a release, deploy it, run a job, and inspect the result.
## Workflows and releases