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

# Overview

> Run and deploy Timbal projects locally or in production

A Timbal project is three layers:

| Layer         | Directory           | Runtime                                        |
| ------------- | ------------------- | ---------------------------------------------- |
| **UI**        | `ui/`               | React + Vite (Bun)                             |
| **API**       | `api/`              | Elysia (Bun) — routes requests to workforce    |
| **Workforce** | `workforce/<name>/` | Python agents/workflows (`timbal.server.http`) |

Each workforce member has its own `timbal.yaml` manifest. The API and UI discover workforce services through env vars (`TIMBAL_START_WORKFORCE`, etc.) that `timbal start` wires up automatically.

## Local development

For day-to-day work, use [`timbal start`](/quickstart#run-locally). It:

* Detects `ui/`, `api/`, and every `workforce/<name>/` with a valid `timbal.yaml`
* Installs dependencies (`bun install`, `uv sync`)
* Picks free ports (defaults: UI `3737`, API `3000`, workforce from `4455`)
* Starts all services and multiplexes logs to one terminal
* Exposes interactive commands (`o` open UI, `s` status, `r` restart, `f`/`m` log focus/mute, `q` quit)

Override ports or env vars when needed:

```bash theme={"dark"}
timbal start --ui-port 4000 --api-port 3001 --port my-agent=4500
timbal start --env OPENAI_API_KEY=sk-... --env my-agent:DEBUG=1
timbal start --env-file .env.staging --env-file api:.env.api
```

## Environment variables

`timbal start` composes a separate environment for each service before spawning it. You do not need `--env-file` for the standard project layout — these files are **auto-loaded** when present:

| File                    | Scope                                          |
| ----------------------- | ---------------------------------------------- |
| `<project>/.env`        | All services (UI, API, every workforce member) |
| `workforce/<name>/.env` | That workforce member only                     |

Missing files are skipped silently.

Override or add variables at the CLI:

```bash theme={"dark"}
timbal start --env DEBUG=1                    # all services
timbal start --env api:LOG_LEVEL=debug      # API only
timbal start --env-file .env.staging        # extra file, all services
timbal start --env-file my-agent:.env.local # extra file, one member
```

`--env` and `--env-file` accept an optional scope prefix: `ui:`, `api:`, or a workforce member name. Unscoped entries apply globally.

### Precedence (low → high)

Later layers win over earlier ones:

1. Timbal built-ins (`TIMBAL_LOG_FORMAT`, `TIMBAL_API_KEY`, etc. from your CLI profile)
2. Inherited shell environment (`PORT` from your shell is ignored so it does not leak into services)
3. Auto-loaded `<project>/.env`, then auto-loaded `workforce/<name>/.env` (members only)
4. `--env-file` (in flag order; scoped files apply only to that service)
5. `--env` (in flag order; scoped entries apply only to that service)
6. Runtime wiring that always wins (`PORT`, `TIMBAL_START_*`, `TIMBAL_WORKFORCE`)

Restart services (`r` in the `timbal start` terminal, or quit and re-run) after changing `.env` files — changes are read at startup, not hot-reloaded.

<Note>
  `.env` parsing is intentionally minimal: `KEY=VALUE` lines, optional `export` prefix, optional quotes, `#` comments. No variable expansion, line continuations, or shell escapes. For complex values, set the variable in your shell or use `--env`.
</Note>

<Tip>
  Vite and Bun may also read `ui/.env` and `api/.env` from those directories at dev time. Project-root `.env` is still the usual place for secrets shared across the stack (model API keys, integration tokens).
</Tip>

## Production

For production you have two paths:

<CardGroup cols={2}>
  <Card title="Timbal Platform" icon="cloud" href="/deployment/platform">
    Managed hosting — connect your git repo, deploy a branch, platform runs UI, API, and workforce for you
  </Card>

  <Card title="Self-hosted" icon="server" href="/deployment/self-hosted">
    Run UI, API, and workforce on your own infra — you own process lifecycle, ports, env wiring, and logging
  </Card>
</CardGroup>

<Tip>
  Validate locally with `timbal start` before deploying. The same project layout is what the platform builds from your repo.
</Tip>