How to Set Up a Self-Hosted Tambo AI Backend: Complete Docker Guide

You can set up a self-hosted Tambo AI backend by cloning the tambo-ai/tambo repository, running the provided setup scripts to generate environment variables, and using Docker Compose to orchestrate the Web, API, and PostgreSQL services.

The tambo-ai/tambo repository provides everything needed to run the entire Tambo AI platform on your own infrastructure. This guide walks through the exact steps to configure and deploy the backend using the official Docker Compose configuration and helper scripts located in scripts/cloud/.

Architecture Overview

A self-hosted Tambo AI deployment consists of three tightly-coupled services defined in docker-compose.yml:

• Web (Next.js) – Runs on port 8260 and serves the dashboard and user interface
• API (NestJS) – Runs on port 8261 and handles REST API requests from clients
• PostgreSQL (PostgreSQL 17) – Runs on port 5433 for persistent data storage

Prerequisites

Before you begin, ensure you have:

• Docker and Docker Compose installed locally
• An OpenAI API key (or compatible LLM provider key) for the fallback language model
• Git to clone the repository

Step-by-Step Self-Hosting Setup

1. Clone the Repository

Start by cloning the official repository and navigating to the project root:

git clone https://github.com/tambo-ai/tambo.git
cd tambo

2. Generate Environment Configuration

Run the setup script to generate the required environment file:

./scripts/cloud/tambo-setup.sh

This script copies docker.env.example to docker.env and prompts you to fill in critical secrets. You must provide:

POSTGRES_PASSWORD=your-secure-password-here
API_KEY_SECRET=your-32-character-api-key-secret
PROVIDER_KEY_SECRET=your-32-character-provider-secret
NEXTAUTH_SECRET=your-nextauth-secret
FALLBACK_OPENAI_API_KEY=your-openai-api-key

You can edit docker.env directly to customize optional variables. See docker.env.example for the full list of available configuration options.

3. Start the Services

Launch all three containers using the start script:

./scripts/cloud/tambo-start.sh

This executes docker compose up -d using the docker-compose.yml definition, starting the Web, API, and PostgreSQL containers in detached mode.

4. Initialize the Database

Apply migrations and seed the database with required tables:

./scripts/cloud/init-database.sh

This script runs the database initialization process, making the API ready to handle requests.

5. Access the Dashboard and API

Once initialization completes, access your self-hosted Tambo AI backend:

• Web Dashboard: http://localhost:8260
• API Endpoint: http://localhost:8261

You can now create projects, configure agents, and manage conversations through the dashboard or API requests.

Production Deployment Considerations

Data Persistence and Storage

For production environments, ensure PostgreSQL data persists beyond container restarts. Mount a host volume or use external storage rather than the default Docker volume. Update the docker-compose.yml volumes section to map to a specific host path.

TLS and Reverse Proxy Configuration

Enable HTTPS by placing a reverse proxy in front of the Web and API services. Configure Traefik or Nginx to handle TLS termination and route traffic to ports 8260 and 8261. Update the NEXTAUTH_URL environment variable to use the HTTPS endpoint.

Kubernetes Scaling

For horizontal scaling, adapt the docker-compose.yml configuration for Kubernetes. The Tambo documentation provides a ready-made Kubernetes manifest at https://tambo.co/docs/guides/self-hosting/kubernetes that separates the Web, API, and database into distinct deployments with proper service discovery.

Monitoring and Backup Strategy

Implement automated backups for the PostgreSQL database using the pg_dump utility or a scheduled container. Configure health checks in docker-compose.yml to monitor container status, and set up log aggregation for the NestJS API and Next.js Web services.

Common Configuration Tasks

CI/CD Pipeline Setup

For automated deployments, use this one-liner to set up the entire stack:

git clone https://github.com/tambo-ai/tambo.git && cd tambo && \
  ./scripts/cloud/tambo-setup.sh && \
  ./scripts/cloud/tambo-start.sh && \
  ./scripts/cloud/init-database.sh

Updating Secrets

To rotate secrets without rebuilding containers, edit docker.env and restart specific services:

sed -i 's/^POSTGRES_PASSWORD=.*/POSTGRES_PASSWORD=$(openssl rand -hex 16)/' docker.env
docker compose restart db

Summary

• Tambo AI self-hosting requires three services: Next.js Web (port 8260), NestJS API (port 8261), and PostgreSQL 17 (port 5433).
• Use ./scripts/cloud/tambo-setup.sh to generate docker.env from the example file, then ./scripts/cloud/tambo-start.sh to launch the stack.
• Run ./scripts/cloud/init-database.sh to apply migrations and prepare the database for use.
• For production, configure persistent storage, TLS termination via reverse proxy, and consider the Kubernetes manifests provided in the official documentation.

Frequently Asked Questions

What are the minimum system requirements for self-hosting Tambo AI?

You need a machine capable of running Docker containers with at least 4GB of RAM and 20GB of available disk space. The PostgreSQL 17 database, NestJS API, and Next.js Web services run concurrently, so allocate additional resources if you expect high concurrent usage or large conversation histories.

Can I use a different LLM provider instead of OpenAI?

Yes, you can configure alternative providers by modifying the FALLBACK_OPENAI_API_KEY and related environment variables in docker.env. The API service in apps/api supports compatible OpenAI API endpoints, allowing you to point to Azure OpenAI, Anthropic via an adapter, or other compatible inference providers.

How do I back up the self-hosted database?

Use standard PostgreSQL tools such as pg_dump to create logical backups of the database running on port 5433. You can run a scheduled backup container that executes pg_dump -h db -U postgres -d tambo > backup.sql against the PostgreSQL service defined in docker-compose.yml, or mount a host volume to the database container and use file-system snapshots.

Where can I find the Kubernetes deployment manifests?

The official Tambo documentation provides ready-made Kubernetes manifests at https://tambo.co/docs/guides/self-hosting/kubernetes. These manifests separate the Web, API, and database components into distinct deployments with proper service discovery, allowing you to scale the self-hosted Tambo AI backend horizontally in a cluster environment.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}