---
title: "Timbal Platform"
description: "Deploy your AI applications seamlessly to the Timbal Platform"
---

The Timbal Platform provides a fully managed deployment environment for your AI applications. With zero infrastructure management required, you can focus entirely on your AI logic while we handle scaling, monitoring, and maintenance.

## Prerequisites

Before deploying to the Timbal Platform, ensure you have:

- [Timbal CLI](/installation) installed and configured
- A Timbal project initialized with `timbal init`
- Your application tested locally

## Deployment Process

<Steps>
  <Step title="Prepare Your Environment">
    Your `timbal init` project comes with a `.dockerignore` file that excludes key files from the build.
    ```bash .dockerignore icon="docker"
    # The .dockerignore file excludes files from the container build process.
    # https://docs.docker.com/engine/reference/builder/#dockerignore-file

    # Exclude Git files
    **/.git
    **/.github
    **/.gitignore

    # Exclude Python cache files
    __pycache__
    .mypy_cache
    .pytest_cache
    .ruff_cache

    # Exclude Python virtual environment - will be recreated in the container
    .venv
    ```
    You can customize the `.dockerignore` to further exclude or include files as needed.
    <Warning>
    All environment variables in your `.env` file and system environment will be included in your container by default. While this is safe, it is preferable to use [platform secrets](/deployment/platform#platform-secrets) for sensitive credentials.
    </Warning>

    Your project also includes a `timbal.yaml` configuration file that defines settings for the build process.

    ```bash timbal.yaml icon="y"
    # Configuration for timbal.️
    # Check the docs for more info: https://docs.timbal.ai/deployment

    build:

        # A list of ubuntu apt packages to install.
        # system_packages:
        #   - "libgl1-mesa-glx"
        #   - "libglib2.0-0"

        # Commands run after the environment is setup.
        # run:
        #   - "echo env is ready!"
        #   - "echo another command if needed"

    # Fully Qualified Name (FQN) to the timbal app to run.
    fqn: "agent.py::agent"
    ```

    The `fqn` (Fully Qualified Name) field specifies which agent or workflow to execute. In this example, `agent.py::agent` refers to the `agent` object in the `agent.py` file.

  </Step>
  <Step title="Build Your Application">
    Build the Docker image with the following command.
    ```bash
    timbal build
    ```
    You can customize the final Docker tag with the `-t` option. If you don't specify a tag, Timbal will use your project name with `:latest` (e.g., `my-project:latest`).
    ```bash
    timbal build -t my-app:v1.0.0
    ```
    This creates a production-ready Docker container with your Timbal application and all dependencies.
  </Step>
  <Step title="Push to Platform">
    Deploy your application to the Timbal Platform:
    ```bash
    timbal push <image_tag> <deployment_url>
    ```
    Replace `<image_tag>` with the tag generated by `timbal build`, and `<deployment_url>` with the URL provided by the Timbal Platform when you create your app.
    <Note>
    This automatically creates a new version of your application with built-in version control, allowing you to rollback, manage multiple environments, and track deployment history.
    </Note>
  </Step>
</Steps>

## Platform Secrets

For enhanced security, and as a best practice, use Timbal Platform environment variables and secrets instead of embedding credentials in your Docker image:

1. **Navigate to your app dashboard** on the [Timbal Platform](https://platform.timbal.ai) <Icon icon="arrow-up-right-from-square" size="10" />
2. **Go to "Environment Variables"**
3. **Add your sensitive credentials** as platform secrets
4. **Reference them in your code** using standard environment variable names

Platform secrets are injected at runtime and never stored in your Docker image, providing better security and easier credential rotation. 

You can further customize environment variables for specific versions of your deployment, allowing different configurations across staging, production, or other environments.

## Connecting to Your Application

Once deployed, your Timbal application becomes available through any interface you connect it to within the platform, plus a built-in REST API for programmatic & agentic access.

### Platform Interfaces
Your application will be accessible through any interface you configure in the Timbal Platform, including web dashboards, chat interfaces, webhooks, and custom integrations.

### REST API
Your deployed application automatically exposes a REST API for direct programmatic access:

```
POST https://dev.timbal.ai/orgs/{org_id}/apps/{app_id}/runs/collect
```

Or for streaming:

```
POST https://dev.timbal.ai/orgs/{org_id}/apps/{app_id}/runs/stream
```

For complete API documentation, including authentication, request/response formats, and SDKs, visit the [API Reference](/api-reference/introduction).

## Monitoring and Logs

The Timbal Platform provides built-in monitoring and logging:

- **Real-time logs** in the platform dashboard
- **Performance metrics** including response times and error rates
- **Resource usage** monitoring for scaling decisions
- **Alert configuration** for critical events

<Tip>
Your application automatically scales based on demand. Monitor the metrics dashboard to understand your usage patterns and optimize performance.
</Tip>
