> ## 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 to a connected git repo and deploy from the platform.

## Prerequisites

* A project scaffolded with [`timbal create`](/quickstart#create-a-timbal-project)
* Code pushed to a git remote the platform can access (typically GitHub)
* [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 push to your remote:

    ```bash theme={"dark"}
    timbal create my-project
    cd my-project
    git remote add origin git@github.com:your-org/my-project.git
    git push -u origin main
    ```
  </Step>

  <Step title="Connect the repo on the platform">
    In the [Timbal Platform](https://app.timbal.ai), create a project linked to that repository. Create environments for the branches you want to deploy (production, staging, etc.).
  </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>

## `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://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](/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>