Self-Hosting Quickstart

Overview

This guide walks you through setting up Tesslate Studio locally using Docker Compose. By the end, you will have a fully functional AI-powered app builder running on your machine, complete with a code editor, live preview, AI chat, and project templates. You do not need Node.js or Python installed on your host machine. Everything runs inside Docker containers.

Looking for the cloud version? Check out tesslate.com for our hosted offering with zero setup required.

Prerequisites

Docker Desktop

Windows/Mac: Download Docker DesktopLinux: curl -fsSL https://get.docker.com | shMake sure Docker Compose v2 is included (it ships with Docker Desktop by default).

System Requirements

RAM: 8 GB minimum (16 GB recommended)
Disk: 10 GB free space (Docker images and volumes)
OS: Windows (WSL 2 backend), macOS, or Linux

AI Provider Key

You need a LiteLLM endpoint or at least one AI provider API key:

OpenAI (GPT-4, GPT-3.5)
Anthropic (Claude 3.5 Sonnet, Claude 3 Opus)
Or a self-hosted LiteLLM proxy

Git

Download from git-scm.com

Installation

Clone the Repository

git clone https://github.com/TesslateAI/Studio.git
cd Studio

Create Your Environment File

Copy the example configuration and open it for editing:

cp .env.example .env

Configure Required Variables

Open .env in your editor and set these required values:

# REQUIRED: A random secret used for JWT signing and encryption.
# Generate one with: python3 -c "import secrets; print(secrets.token_urlsafe(32))"
SECRET_KEY=your-secret-key-here-change-this

# REQUIRED: LiteLLM configuration for AI features.
# Point this at your LiteLLM proxy or compatible endpoint.
LITELLM_API_BASE=https://your-litellm-url.com/v1
LITELLM_MASTER_KEY=your-litellm-master-key

# OPTIONAL but recommended: comma-separated list of models to offer users.
LITELLM_DEFAULT_MODELS=gpt-4o-mini,claude-3-5-sonnet-20241022

Everything else has sensible defaults for local development. See the full Configuration Reference for all available options.

How to generate a secure SECRET_KEY

Run one of these commands and paste the output into your .env file:

# Python (works on all platforms)
python3 -c "import secrets; print(secrets.token_urlsafe(32))"

# OpenSSL (Linux/Mac)
openssl rand -base64 32

Build and Start All Services

docker compose up --build -d

This builds two images from source and pulls two from Docker Hub:

Service	Image Source	Description
`orchestrator`	Built from `orchestrator/Dockerfile`	FastAPI backend (Python 3.11)
`app`	Built from `app/Dockerfile`	React frontend (Vite dev server)
`postgres`	`postgres:15-alpine` (pulled)	PostgreSQL database
`traefik`	`traefik:v3.1` (pulled)	Reverse proxy for routing

The first build takes about 1 to 2 minutes. Subsequent starts are much faster.

Build the Devserver Image

The devserver image powers user project containers (the isolated environments that run your app code). It is not part of docker-compose.yml, so you must build it separately:

docker build -t tesslate-devserver:latest -f orchestrator/Dockerfile.devserver orchestrator/

Without this image, creating or starting any user project will fail with a pull access denied for tesslate-devserver error.

Verify Everything Is Running

docker compose ps

You should see output similar to:

NAME                    IMAGE                          STATUS                  PORTS
tesslate-app            tesslate-studio-app            Up (healthy)            0.0.0.0:5173->5173/tcp
tesslate-orchestrator   tesslate-studio-orchestrator   Up (healthy)            0.0.0.0:8000->8000/tcp
tesslate-postgres-dev   postgres:15-alpine             Up (healthy)            0.0.0.0:5432->5432/tcp
tesslate-traefik        traefik:v3.1                   Up                      0.0.0.0:80->80/tcp

All services should show Up (and healthy where applicable). The orchestrator may show health: starting for up to 30 seconds while it runs database migrations.

Access the Application

Open your browser and navigate to:

URL	Description
http://localhost	Frontend via Traefik (recommended)
http://localhost:5173	Vite dev server directly
http://localhost:8000/docs	Swagger API documentation
http://localhost:8080	Traefik admin dashboard

The database is auto-initialized on first startup (tables created via Alembic migrations).

Seed the Database

After the first startup, seed marketplace data (project templates, AI agents, themes):

# Copy seed scripts into the backend container
docker cp scripts/seed/seed_marketplace_bases.py tesslate-orchestrator:/tmp/
docker cp scripts/seed/seed_marketplace_agents.py tesslate-orchestrator:/tmp/
docker cp scripts/seed/seed_opensource_agents.py tesslate-orchestrator:/tmp/
docker cp scripts/seed/seed_themes.py tesslate-orchestrator:/tmp/
docker exec tesslate-orchestrator mkdir -p /tmp/themes
docker cp scripts/themes/. tesslate-orchestrator:/tmp/themes/

# Run seed scripts (order matters: bases first, then agents, then themes)
docker exec -e PYTHONPATH=/app tesslate-orchestrator python /tmp/seed_marketplace_bases.py
docker exec -e PYTHONPATH=/app tesslate-orchestrator python /tmp/seed_marketplace_agents.py
docker exec -e PYTHONPATH=/app tesslate-orchestrator python /tmp/seed_opensource_agents.py

All seed scripts are idempotent, so it is safe to re-run them without duplicating data.

What gets seeded?

Data	Count	Examples
Project templates	4	Next.js 16, Vite+React+FastAPI, Vite+React+Go, Expo
Official agents	5	Stream Builder, Tesslate Agent, React Component Builder, API Integration, ReAct Agent
Open-source agents	6	Code Analyzer, Doc Writer, Refactoring Assistant, Test Generator, API Designer, DB Schema Designer
Themes	7	default-dark, default-light, midnight, ocean, forest, rose, sunset

Create Your First Project

Click “Sign Up” to create your account (the first user gets admin privileges)
Click “New Project” on the dashboard
Choose a starter template (for example, Vite + React + FastAPI)
Give your project a name and click “Create”
Try typing in the chat: Create a simple todo app with add, delete, and mark complete functionality

Your self-hosted Tesslate Studio is now running. You have a code editor, live preview, AI chat, and file browser all in your browser.

What Gets Created

Docker Resources

Resource	Name	Purpose
Image	`tesslate-studio-orchestrator`	FastAPI backend (~870 MB)
Image	`tesslate-studio-app`	React frontend (~760 MB)
Image	`tesslate-devserver`	User project runtime (~1.2 GB)
Volume	`tesslate-postgres-dev-data`	PostgreSQL data (persists between restarts)
Volume	`tesslate-base-cache`	Pre-installed marketplace templates
Volume	`tesslate-projects-data`	All user project source code
Network	`tesslate-network`	Bridge network connecting all services

Routing (Traefik)

Path Pattern	Destination	Priority
`/api/*`	`orchestrator:8000`	100
`/ws/*`	`orchestrator:8000`	100
`/*` (everything else)	`app:5173`	10
`*.localhost`	User project containers	Auto-discovered

Development Workflow

Hot Reload

Both backend and frontend support automatic reloading via volume mounts:

Backend: Edit files in orchestrator/app/. Uvicorn detects changes and reloads automatically.
Frontend: Edit files in app/src/. Vite HMR updates the browser instantly.

No rebuild is needed for code changes.

When to Rebuild

Rebuild only when dependencies change (new packages added to pyproject.toml or package.json):

# Rebuild a specific service
docker compose up -d --build orchestrator
docker compose up -d --build app

# Rebuild everything
docker compose up -d --build

Viewing Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f orchestrator
docker compose logs -f app
docker compose logs -f postgres

Shell Access

# Backend container (Python/bash)
docker compose exec orchestrator bash

# Frontend container (Alpine sh)
docker compose exec app sh

# Database (psql)
docker compose exec postgres psql -U tesslate_user -d tesslate_dev

Database Migrations

# Apply pending migrations
docker compose exec orchestrator alembic upgrade head

# Create a new migration
docker compose exec orchestrator alembic revision --autogenerate -m "description"

# Roll back one migration
docker compose exec orchestrator alembic downgrade -1

Clean Slate Reset

To completely reset everything (database, images, volumes) and start fresh:

# 1. Stop and remove containers, volumes, and orphans
docker compose down --volumes --remove-orphans

# 2. Remove all Tesslate images
docker images --format "{{.Repository}}:{{.Tag}} {{.ID}}" | grep -i tesslate | awk '{print $2}' | sort -u | xargs docker rmi -f

# 3. Rebuild and start fresh
docker compose up --build -d

Troubleshooting

Cannot access localhost or studio.localhost

Symptoms: The browser shows “connection refused” or “site can’t be reached.”Steps to resolve:

Verify Docker is running: Open Docker Desktop and confirm it says “Docker is running.”
Check container status:
```
docker compose ps
```
All services should show Up.
Check orchestrator logs for startup errors:
```
docker compose logs orchestrator
```
Try the direct ports: Access http://localhost:5173 (frontend) or http://localhost:8000/docs (API docs) to bypass Traefik.

Restart everything:

docker compose down
docker compose up -d

Port already in use

Symptom: bind: address already in use when starting containers.Solution: Change the conflicting port in your .env file:

APP_PORT=8081        # default: 80
BACKEND_PORT=8001    # default: 8000
FRONTEND_PORT=5174   # default: 5173
POSTGRES_PORT=5433   # default: 5432

Then restart: docker compose up -d

Orchestrator fails health check (shows 'unhealthy')

Common causes:

Database not ready yet. The orchestrator waits for PostgreSQL. Give it 30 seconds.
Missing required environment variables. Check that SECRET_KEY and LITELLM_API_BASE are set in .env.
Port conflict on 8000. Another process may be using that port.

Check logs for details:

docker compose logs orchestrator

Hot reload not working

Backend (Uvicorn):

Confirm WATCHFILES_FORCE_POLLING=true is set (already in docker-compose.yml by default).
Check logs: docker compose logs -f orchestrator and look for “Reloading…”

Frontend (Vite):

Confirm CHOKIDAR_USEPOLLING=true is set (already in docker-compose.yml by default).
Check your browser console for HMR connection errors.
Try a hard refresh: Ctrl+Shift+R.

User project container not starting

Symptom: Creating a project fails with pull access denied for tesslate-devserver.Cause: You have not built the devserver image.Fix:

docker build -t tesslate-devserver:latest -f orchestrator/Dockerfile.devserver orchestrator/

Database connection errors

# Check if PostgreSQL is running
docker compose ps postgres

# Test connection from inside the container
docker compose exec postgres pg_isready -U tesslate_user -d tesslate_dev

If the database is corrupted, reset it:

docker compose down
docker volume rm tesslate-postgres-dev-data
docker compose up -d

Removing the database volume deletes all existing data.

LITELLM_DEFAULT_MODELS warning

If you see The "LITELLM_DEFAULT_MODELS" variable is not set. Defaulting to a blank string., this is harmless. Suppress it by adding to .env:

LITELLM_DEFAULT_MODELS=gpt-4o-mini

Advanced: Hybrid Development Mode

For faster iteration during development, you can run the backend and frontend natively on your host while keeping infrastructure in Docker:

Full Docker (Recommended for most users)
Hybrid Mode (Native backend and frontend)

docker compose up -d

Everything runs in containers. Simple and fully isolated.

# Terminal 1: Start infrastructure only
docker compose up -d traefik postgres

# Terminal 2: Run backend with hot reload
cd orchestrator
uv run uvicorn app.main:app --reload --port 8000

# Terminal 3: Run frontend with hot reload
cd app
npm run dev

Frontend at http://localhost:5173, backend at http://localhost:8000.

Stopping and Restarting

docker compose down

Next Steps

Configuration Reference

All environment variables, grouped by category, with examples

Production Deployment

Deploy to production with Docker Compose, Kubernetes, or AWS EKS

Architecture Overview

Understand the multi-tier design, data flow, and security model

API Documentation

Explore the REST API with Swagger

Getting Help

GitHub Discussions

Ask questions and share ideas

GitHub Issues

Report bugs and request features

Email Support

Direct support (response within 24h)

Documentation

Browse the full documentation

Get Started

Self-Hosting

Core Concepts

Working with Projects

AI Agents

Advanced Features

Developer Guide

Development

Overview

Prerequisites

Docker Desktop

System Requirements

AI Provider Key

Git

Installation

What Gets Created

Docker Resources

Routing (Traefik)

Development Workflow

Hot Reload

When to Rebuild

Viewing Logs

Shell Access

Database Migrations

Clean Slate Reset

Troubleshooting

Advanced: Hybrid Development Mode

Stopping and Restarting

Next Steps

Configuration Reference

Production Deployment

Architecture Overview

API Documentation

Getting Help

GitHub Discussions

GitHub Issues

Email Support

Documentation

Get Started

Self-Hosting

Core Concepts

Working with Projects

AI Agents

Advanced Features

Developer Guide

Development

​Overview

​Prerequisites

Docker Desktop

System Requirements

AI Provider Key

Git

​Installation

​What Gets Created

​Docker Resources

​Routing (Traefik)

​Development Workflow

​Hot Reload

​When to Rebuild

​Viewing Logs

​Shell Access

​Database Migrations

​Clean Slate Reset

​Troubleshooting

​Advanced: Hybrid Development Mode

​Stopping and Restarting

​Next Steps

Configuration Reference

Production Deployment

Architecture Overview

API Documentation

​Getting Help

GitHub Discussions

GitHub Issues

Email Support

Documentation

Overview

Prerequisites

Installation

What Gets Created

Docker Resources

Routing (Traefik)

Development Workflow

Hot Reload

When to Rebuild

Viewing Logs

Shell Access

Database Migrations

Clean Slate Reset

Troubleshooting

Advanced: Hybrid Development Mode

Stopping and Restarting

Next Steps

Getting Help