Timbal Platform

The Timbal Platform runs your project’s UI, API, and workforce components for you. There is no local timbal build or Docker workflow — you push code to a connected git repo and deploy from the platform.

Prerequisites

A project scaffolded with timbal create
Code pushed to a git remote the platform can access (typically GitHub)
Timbal CLI installed (timbal configure for local credentials if needed)
The project tested locally with timbal start

How deployment works

Each platform project maps to a git repository. Environments map to git branches (e.g. main → production, staging → staging). When you deploy an environment, the platform:

Checks out the requested git rev (branch)
Reads each workforce/<name>/timbal.yaml manifest
Builds and runs the UI, API, and every workforce member as separate deployable units
Routes traffic through a shared gateway (proj-env-<env_id>.deployments.timbal.ai)

Create and push your project

Scaffold locally, develop with timbal start, then push to your remote:

timbal create my-project
cd my-project
git remote add origin git@github.com:your-org/my-project.git
git push -u origin main

Connect the repo on the platform

In the Timbal Platform, create a project linked to that repository. Create environments for the branches you want to deploy (production, staging, etc.).

Configure secrets

Add environment variables and secrets in the platform dashboard — model API keys, integration tokens, anything sensitive. These are injected at runtime and are not baked into your repo.Reference them in code with standard env var names (e.g. OPENAI_API_KEY).

Deploy

Trigger a deploy for the target environment from the platform UI (or via the Deploy API). The platform deploys the git rev for that environment’s branch.Deployments are idempotent on the same rev. Re-deploy after pushing new commits to pick up changes.

`timbal.yaml` manifest

Every workforce member needs a timbal.yaml. timbal create generates one automatically — do not remove the _id or _type fields.

workforce/<name>/timbal.yaml

# Auto-generated. Do not modify _id / _type by hand unless you know what you're doing.
_id: "a1b2c3d4-..."
_type: "agent"   # or "workflow"

build:
  # Optional: apt packages for the platform build environment
  # system_packages:
  #   - "libgl1-mesa-glx"

  # Optional: commands run after the environment is set up
  # run:
  #   - "echo env is ready!"

# Which runnable to serve (relative to this directory)
fqn: "agent.py::agent"

Field	Purpose
`_id`	Stable manifest UUID — used for routing, logs, and deployment identity
`_type`	`agent` or `workflow`
`fqn`	Import spec for the Python runnable (`file.py::object`)
`build.system_packages`	Ubuntu packages installed during platform build
`build.run`	Shell commands run after dependency install

Add additional workforce members locally with timbal add — each gets its own directory and manifest.

Accessing a deployed project

Once live, the environment gateway exposes:

UI at the environment root
API at /api/...
Workforce at /api/workforce/<member>/... (proxied to each member’s HTTP server)

For programmatic access outside the gateway, the platform also exposes run endpoints:

POST https://dev.timbal.ai/orgs/{org_id}/apps/{app_id}/runs/collect
POST https://dev.timbal.ai/orgs/{org_id}/apps/{app_id}/runs/stream

See the API Reference for auth, request shapes, and SDK usage.

Monitoring and logs

The platform dashboard provides:

Deployment status per component (UI, API, workforce members)
Runtime logs filtered by component
Resource usage and deploy history

You can also fetch logs via the environment logs API.

Even when self-hosting workforce runtimes, you can point tracing at the platform — see Tracing.

Getting started

Core Concepts

Agents

Workflows

Human in the Loop

Evals

Deployment

Timbal Platform

Prerequisites

How deployment works

`timbal.yaml` manifest

Accessing a deployed project

Monitoring and logs

​Prerequisites

​How deployment works

​timbal.yaml manifest

​Accessing a deployed project

​Monitoring and logs

Prerequisites

How deployment works

`timbal.yaml` manifest

Accessing a deployed project

Monitoring and logs