Getting Started

This guide walks you through setting up TeamWeb AI and creating your first AI assistant.

Overview

TeamWeb AI is a self-hosted AI assistant platform built with Flask and Docker. It lets you create intelligent assistants that can:

Have text and voice conversations with users
Search and reference knowledge bases
Generate content like blog posts and articles
Execute code in sandboxed environments
Run automated tasks on a schedule
Communicate via email channels
Serve public chat interfaces for website visitors

Requirements

Before you begin, make sure you have:

Docker and Docker Compose installed
An LLM provider API key (e.g. Anthropic, OpenAI) — you can also paste in a Claude Code or ChatGPT subscription via OAuth from the Settings UI later
About 2 GB free disk space for the local embedding and reranker models

Installation

Clone the Repository

git clone https://github.com/teamwebhq/teamwebai.git
cd teamwebai

Configure Environment Variables

Copy the example environment file:

cp .env.example .env

Then generate a SECRETS_ENCRYPTION_KEY and paste it into .env:

python3 -c "import base64, os; print(base64.b64encode(os.urandom(32)).decode())"

The app refuses to start without this key. It encrypts LLM provider API keys, OAuth refresh tokens, MCP credentials, channel plugin tokens, and system webhook signing secrets at rest. Keep it stable — rotating it without a re-encryption step makes existing encrypted rows unreadable. See Secrets for details.

The shipped .env.example uses the well-known development database password teamwebai_dev_password. That is fine for a Compose stack running on your laptop. Never use it for anything reachable from the network — change it (and rebuild the db volume) before exposing the stack.

Download the Local Models

tools/download_models.sh

The containers run with HF_HUB_OFFLINE=1, so these files must exist on disk before the app starts. Total download is ~1 GB (embedder all-MiniLM-L6-v2 plus reranker BAAI/bge-reranker-v2-m3). Re-run this script whenever the default model names change.

Start the Application

tools/build.sh

This builds the web image (including the sandbox image) and starts all services: web, worker, beat, db, and redis.

Open the App

Navigate to http://localhost:5050 in your browser.

Run the Setup Wizard

On first launch, the setup wizard will guide you through:

Creating your admin user account
Configuring your LLM provider (the AI model that powers your assistants)
Configuring your embedding provider (used for knowledge search)

Optional Setup Steps

Browser Automation

If you want assistants to drive a real browser (navigate, click, extract content, screenshot), install Chromium for Playwright on the host:

uv run patchright install chromium

The browser automation features work without this; they will fail at runtime if invoked. Skip this step if you do not need them.

First Steps After Setup

Once the setup wizard is complete, you’re ready to start using TeamWeb AI.

Configure Providers

Set up your LLM and embedding providers

Create an Assistant

Build your first AI assistant

Set Up a Project

Add knowledge and content guidelines

Architecture

TeamWeb AI runs as a set of Docker containers:

Service	Purpose
web	Flask application server
worker	Celery worker for background tasks (AI conversations, scheduled tasks, email handling)
beat	Celery Beat for scheduled task dispatch
db	PostgreSQL with pgvector for data and vector search
redis	Message broker and rate-limit cache

The web application handles all user interactions; the worker processes long-running and scheduled work.