Self-Hosting with Docker

Overview

Tambo can be self-hosted on your infrastructure using Docker. You get the same features as Tambo Cloud but with complete control over deployment, data, and scaling. The self-hosted stack includes:

Web Dashboard (Next.js) - User interface for managing projects and API keys
API Service (NestJS) - Backend handling agent execution and conversation state
PostgreSQL - Database for threads, messages, and configuration
MinIO (optional) - S3-compatible storage for file uploads

Architecture

Tambo consists of three main services:

Service	Technology	Port	Description
web	Next.js	8260	Dashboard and UI
api	NestJS	8261	REST API and agent execution
postgres	PostgreSQL 17	5433	Data persistence

Prerequisites

Docker and Docker Compose installed
OpenAI API key (or compatible provider)
2GB+ RAM available
Ports 8260, 8261, and 5433 available

Clone the Repository

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

Run Setup Script

The setup script creates your environment configuration:

./scripts/cloud/tambo-setup.sh

This generates docker.env from docker.env.example with placeholder values.

Configure Environment Variables

Edit docker.env and set required values:

# Database (required)
POSTGRES_PASSWORD=your-secure-password-here
POSTGRES_USER=postgres
POSTGRES_DB=tambo

# Security secrets (required - use 32+ character random strings)
API_KEY_SECRET=your-32-character-api-key-secret
PROVIDER_KEY_SECRET=your-32-character-provider-secret
NEXTAUTH_SECRET=your-nextauth-secret

# LLM Provider (required)
FALLBACK_OPENAI_API_KEY=your-openai-api-key

# URLs (required for production)
NEXTAUTH_URL=http://localhost:8260
NEXT_PUBLIC_TAMBO_API_URL=http://localhost:8261

Never commit docker.env to version control. It contains secrets.

Start Services

Build and start all containers:

./scripts/cloud/tambo-start.sh

This command:

Builds Docker images for web and API

Starts PostgreSQL, web, and API containers

Runs health checks

First startup takes 5-10 minutes for image building.

Initialize Database

Run migrations to set up the database schema:

./scripts/cloud/init-database.sh

This applies all migrations from packages/db/migrations/.

Access Your Deployment

Open your browser:

Web Dashboard: http://localhost:8260

API: http://localhost:8261

API Health Check: http://localhost:8261/health

Create an account and generate an API key to start building.

Environment Variables

Required Variables

These must be set for Tambo to function:

# Database
POSTGRES_PASSWORD=your-secure-password
POSTGRES_USER=postgres
POSTGRES_DB=tambo

# Encryption secrets (32+ characters)
API_KEY_SECRET=your-api-key-encryption-secret
PROVIDER_KEY_SECRET=your-provider-key-encryption-secret

# NextAuth (generate with: openssl rand -base64 32)
NEXTAUTH_SECRET=your-nextauth-secret
NEXTAUTH_URL=http://localhost:8260

# LLM Provider
FALLBACK_OPENAI_API_KEY=sk-...

Optional Variables

# OAuth Providers
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

# Email (Resend)
RESEND_API_KEY=re_...
EMAIL_FROM_DEFAULT=noreply@yourdomain.com

# Observability
LANGFUSE_PUBLIC_KEY=pk-...
LANGFUSE_SECRET_KEY=sk-...
LANGFUSE_HOST=https://cloud.langfuse.com

# Analytics
POSTHOG_API_KEY=phc_...
POSTHOG_HOST=https://app.posthog.com

# Sentry
SENTRY_DSN=https://...@sentry.io/...

Docker Compose Services

Web Service

web:
  image: tambo-web:latest
  build:
    context: .
    dockerfile: apps/web/Dockerfile
  ports:
    - "8260:3000"
  depends_on:
    - postgres
    - api

API Service

api:
  image: tambo-api:latest
  build:
    context: .
    dockerfile: apps/api/Dockerfile
  ports:
    - "8261:3000"
  depends_on:
    - postgres

PostgreSQL

postgres:
  image: postgres:17
  ports:
    - "5433:5432"
  volumes:
    - tambo_postgres_data:/var/lib/postgresql/data
  environment:
    POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    POSTGRES_USER: ${POSTGRES_USER}
    POSTGRES_DB: ${POSTGRES_DB}

Management Scripts

Tambo includes helper scripts in scripts/cloud/:

Start/Stop Services

# Start all services
./scripts/cloud/tambo-start.sh

# Stop all services
docker compose down

# Stop and remove volumes (deletes data)
docker compose down -v

Database Operations

# Initialize database (first time)
./scripts/cloud/init-database.sh

# Run migrations
docker compose exec api npm run db:migrate

# Open database shell
docker compose exec postgres psql -U postgres -d tambo

Logs

# View all logs
docker compose logs -f

# View specific service
docker compose logs -f api
docker compose logs -f web
docker compose logs -f postgres

# View last 100 lines
docker compose logs --tail=100 api

Rebuilding

# Rebuild specific service
docker compose build api
docker compose up -d api

# Rebuild all services
docker compose build
docker compose up -d

# Force rebuild without cache
docker compose build --no-cache

Production Deployment

Security Checklist

Use strong secrets

Generate secure random values for all secrets:

# Generate 32-character secret
openssl rand -base64 32

# Generate API key secret
openssl rand -hex 32

Enable HTTPS

Use a reverse proxy (nginx, Caddy, Traefik) with SSL certificates:

server {
  listen 443 ssl http2;
  server_name tambo.yourdomain.com;
  
  ssl_certificate /path/to/cert.pem;
  ssl_certificate_key /path/to/key.pem;
  
  location / {
    proxy_pass http://localhost:8260;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
  }
}

Restrict network access

Use Docker networks to isolate services:

services:
  postgres:
    networks:
      - internal
    # Don't expose port publicly
  
  api:
    networks:
      - internal
      - public

networks:
  internal:
    internal: true
  public:

Set up authentication

Configure OAuth providers or email login:

GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
RESEND_API_KEY=...  # For email login

Scaling

For production load:

Horizontal scaling: Run multiple API instances behind a load balancer
Database: Use managed PostgreSQL (AWS RDS, Cloud SQL, etc.)
Caching: Add Redis for session storage
File storage: Use S3 or compatible object storage

Monitoring

# Check health endpoints
curl http://localhost:8261/health

# Monitor resource usage
docker stats

# Set up Sentry for error tracking
SENTRY_DSN=https://...@sentry.io/...

# Enable Langfuse for LLM observability
LANGFUSE_PUBLIC_KEY=...
LANGFUSE_SECRET_KEY=...

Backup and Restore

Backup Database

# Backup to file
docker compose exec postgres pg_dump -U postgres tambo > backup.sql

# Backup with compression
docker compose exec postgres pg_dump -U postgres tambo | gzip > backup.sql.gz

Restore Database

# Restore from backup
docker compose exec -T postgres psql -U postgres tambo < backup.sql

# Restore compressed backup
gunzip < backup.sql.gz | docker compose exec -T postgres psql -U postgres tambo

Automated Backups

#!/bin/bash
# backup.sh - Run daily via cron

BACKUP_DIR="/backups/tambo"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p "$BACKUP_DIR"
docker compose exec postgres pg_dump -U postgres tambo | gzip > "$BACKUP_DIR/backup_$DATE.sql.gz"

# Keep last 7 days
find "$BACKUP_DIR" -name "backup_*.sql.gz" -mtime +7 -delete

Troubleshooting

Services won't start

Check logs for errors:

docker compose logs api
docker compose logs web

Common issues:

Port conflicts (8260, 8261, 5433 in use)
Missing environment variables
Database connection failed

Database connection errors

Verify PostgreSQL is running:

docker compose ps postgres
docker compose logs postgres

Check connection string:

DATABASE_URL=postgresql://postgres:password@postgres:5432/tambo

API returns 500 errors

Check API logs:

docker compose logs -f api

Common causes:

Missing migrations (run init-database.sh)
Invalid API key secrets
LLM provider key not set

Web dashboard won't load

Verify web service is running:

docker compose ps web
curl http://localhost:8260

Check environment:

NEXT_PUBLIC_TAMBO_API_URL=http://localhost:8261
NEXTAUTH_URL=http://localhost:8260

Updating

Update to Latest Version

# Pull latest code
git pull origin main

# Rebuild images
docker compose build

# Run migrations
./scripts/cloud/init-database.sh

# Restart services
docker compose up -d

Version Pinning

For production, pin to specific versions:

services:
  web:
    image: tambo-web:1.0.0
  api:
    image: tambo-api:1.0.0

Next Steps

Environment Variables

Complete environment variable reference

Kubernetes Deployment

Deploy to Kubernetes

Operations Guide

Backup, monitoring, and maintenance

Troubleshooting

Common issues and solutions

Get Started

Core Concepts

Guides

Templates & Examples

Self-Hosting with Docker

Overview

Architecture

Prerequisites

Environment Variables

Required Variables

Optional Variables

Docker Compose Services

Web Service

API Service

PostgreSQL

Management Scripts

Start/Stop Services

Database Operations

Logs

Rebuilding

Production Deployment

Security Checklist

Scaling

Monitoring

Backup and Restore

Backup Database

Restore Database

Automated Backups

Troubleshooting

Updating

Update to Latest Version

Version Pinning

Next Steps

Environment Variables

Kubernetes Deployment

Operations Guide

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Templates & Examples

Documentation Index

​Overview

​Architecture

​Prerequisites

​Environment Variables

​Required Variables

​Optional Variables

​Docker Compose Services

​Web Service

​API Service

​PostgreSQL

​Management Scripts

​Start/Stop Services

​Database Operations

​Logs

​Rebuilding

​Production Deployment

​Security Checklist

​Scaling

​Monitoring

​Backup and Restore

​Backup Database

​Restore Database

​Automated Backups

​Troubleshooting

​Updating

​Update to Latest Version

​Version Pinning

​Next Steps

Environment Variables

Kubernetes Deployment

Operations Guide

Troubleshooting

Build docs developers (and LLMs) love

Overview

Architecture

Prerequisites

Environment Variables

Required Variables

Optional Variables

Docker Compose Services

Web Service

API Service

PostgreSQL

Management Scripts

Start/Stop Services

Database Operations

Logs

Rebuilding

Production Deployment

Security Checklist

Scaling

Monitoring

Backup and Restore

Backup Database

Restore Database

Automated Backups

Troubleshooting

Updating

Update to Latest Version

Version Pinning

Next Steps