> ## Documentation Index
> Fetch the complete documentation index at: https://docs.timbal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Timbal Platform

> Deploy Timbal projects to managed hosting

The [Timbal Platform](https://app.timbal.ai) runs your project's UI, API, and workforce components for you. There is no local `timbal build` or Docker workflow — you push code with `timbal push` and deploy from the platform.

## Prerequisites

* A project scaffolded with [`timbal create`](/quickstart#create-a-timbal-project)
* [Timbal CLI](/installation) installed (`timbal configure` for local credentials if needed)
* The project tested locally with [`timbal start`](/quickstart#run-locally)

## 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`)

<Steps>
  <Step title="Create and push your project">
    Scaffold locally, develop with `timbal start`, then commit and push:

    ```bash theme={"dark"}
    timbal create my-project
    cd my-project
    timbal configure
    git add .
    git commit -m "Initial project"
    timbal push
    ```
  </Step>

  <Step title="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](https://app.timbal.ai). Pushing discovers your components and provisions new branch environments. Pushes to an existing environment follow the platform’s normal deployment behavior.
  </Step>

  <Step title="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`).
  </Step>

  <Step title="Deploy">
    Trigger a deploy for the target environment from the platform UI (or via the [Deploy API](/api-reference/projects/environments/deploy)). 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.
  </Step>
</Steps>

## 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`.

```bash theme={"dark"}
# 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.

```yaml workforce/<name>/timbal.yaml icon="y" theme={"dark"}
# 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:

```http theme={"dark"}
POST https://api.timbal.ai/orgs/{org_id}/apps/{app_id}/runs/collect
POST https://api.timbal.ai/orgs/{org_id}/apps/{app_id}/runs/stream
```

See the [API Reference](/api-reference/introduction) 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](/api-reference/projects/environments/logs).

<Tip>
  Even when self-hosting workforce runtimes, you can point tracing at the platform — see [Tracing](/core-concepts/tracing).
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.