Skip to main content
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:
  1. Checks out the requested git rev (branch)
  2. Reads each workforce/<name>/timbal.yaml manifest
  3. Builds and runs the UI, API, and every workforce member as separate deployable units
  4. Routes traffic through a shared gateway (proj-env-<env_id>.deployments.timbal.ai)
1

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
2

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.).
3

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).
4

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"
FieldPurpose
_idStable manifest UUID — used for routing, logs, and deployment identity
_typeagent or workflow
fqnImport spec for the Python runnable (file.py::object)
build.system_packagesUbuntu packages installed during platform build
build.runShell 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.