Skip to main content
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 installed and configured
  • A Timbal project initialized with timbal init
  • Your application tested locally

​
Deployment Process

1

Prepare Your Environment

Your timbal init project comes with a .dockerignore file that excludes key files from the build.
.dockerignore
# 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.
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 for sensitive credentials.
Your project also includes a timbal.yaml configuration file that defines settings for the build process.
timbal.yaml
# 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.
2

Build Your Application

Build the Docker image with the following command.
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).
timbal build -t my-app:v1.0.0
This creates a production-ready Docker container with your Timbal application and all dependencies.
3

Push to Platform

Deploy your application to the Timbal Platform:
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.
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.

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

​
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
Your application automatically scales based on demand. Monitor the metrics dashboard to understand your usage patterns and optimize performance.