Timbal Platform

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

Prerequisites

A project scaffolded with timbal create
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 commit and push:

timbal create my-project
cd my-project
timbal configure
git add .
git commit -m "Initial project"
timbal push

Open your linked project

On the first push, the CLI creates a project in your configured organization and adds a timbal Git remote. The platform default branch remains main; the CLI pushes whichever branch you have checked out. Existing Timbal remotes are reused, and GitHub remotes stay intact.Open the project in the Timbal Platform. Pushing discovers your components and provisions new branch environments. Pushes to an existing environment follow the platform’s normal deployment behavior.

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.

Pushing code

timbal push uploads the current branch’s commits using Git. It leaves uncommitted files alone and preserves your existing upstream. To also set the Timbal remote as the branch’s upstream, use timbal push -u.

# First push: optional project name and organization overrides
timbal push --name my-project --org 123

# Select credentials and API host from a configured profile
timbal push --profile dev

# Preview without creating a project or linking a remote
timbal push --dry-run

The default project name is the repository directory name. --name and --org apply only to the first push. Profile selection follows --profile, then TIMBAL_PROFILE, then default, for both project creation and Git authentication. A failed upload keeps the project link, so timbal push retries the same project. For a project created by this command, the initial push to main replaces the generated scaffold using an exact-SHA --force-with-lease. The CLI verifies the scaffold is a single initial commit and saves its SHA before pushing; retries never refresh the lease. A concurrent update causes rejection. Existing linked projects and subsequent pushes use normal Git behavior. Common Git options such as --force-with-lease, --porcelain, and --follow-tags are supported; run timbal push --help for the full list. The command always targets the current branch; use Git directly for other refspecs. Automatic creation uses the existing minimal Scratch scaffold without server-generated workforce members. Your committed UI and workforce code are uploaded by Git; the project’s has_ui metadata retains the creation default because the existing metadata API does not expose that field. If several Timbal remotes exist, name the intended one timbal. A remote named timbal that points elsewhere must be renamed before automatic linking can proceed. Environment variables are separate from code: use timbal env push to upload them and timbal env pull to configure your local environment after the first code push.

`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 /orgs/{org_id}/projects/{project_id}/workforce/{workforce}/run
POST /orgs/{org_id}/projects/{project_id}/workforce/{workforce}/stream

Those paths are the workforce gateway ({*path} on the workforce resource). A self-hosted process exposes the same calls as POST /run and POST /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

Voice Agents

Workflows

Human in the Loop

Evals

Deployment

Timbal Platform

Prerequisites

How deployment works

Pushing code

`timbal.yaml` manifest

Accessing a deployed project

Monitoring and logs

​Prerequisites

​How deployment works

​Pushing code

​timbal.yaml manifest

​Accessing a deployed project

​Monitoring and logs

Prerequisites

How deployment works

Pushing code

`timbal.yaml` manifest

Accessing a deployed project

Monitoring and logs