Tale

Build AI-powered applications in minutes, not months.

Tale is a ready-to-run platform that gives you everything you need: intelligent AI assistants, automated data collection, and a modern web interface—all with a single command.

Quick Start

Get Tale running in 4 steps:

1. Prerequisites

• Docker Desktop (v24+)
• OpenRouter API Key

2. Configure Local Domain

Add tale.local to your hosts file so your browser can find the local server:

macOS / Linux:

echo "127.0.0.1 tale.local" | sudo tee -a /etc/hosts

Windows (run PowerShell as Administrator):

Add-Content -Path "C:\Windows\System32\drivers\etc\hosts" -Value "127.0.0.1 tale.local"

3. Clone & Configure

git clone https://github.com/tale-project/tale.git
cd tale
cp .env.example .env

Edit .env and add your OpenRouter API key:

OPENAI_API_KEY=your-openrouter-api-key

4. Launch

docker compose up --build

That's it! Open https://tale.local when you see "Server ready".

Note: Your browser will show a certificate warning because Tale uses self-signed certificates for local development. This is safe to accept. To avoid the warning, run: docker exec tale-proxy caddy trust

What Can You Do?

Once Tale is running, you can:

Goal	How
Use the main app	Visit your configured domain (default: https://tale.local)
Chat with AI assistants	Built into the platform—start chatting immediately
Crawl websites for data	Add URLs through the interface or Crawler API
Search your data with AI	Use natural language queries in the app
View backend data	Generate admin key (see below) and open Convex Dashboard
Test APIs directly	Interactive docs at RAG API endpoint

Deploy to Production

Using Docker Compose (Simple)

Update your .env file and start:

HOST=yourdomain.com
SITE_URL=https://yourdomain.com
TLS_MODE=letsencrypt

docker compose up --build -d

SSL certificates are automatically provisioned via Let's Encrypt.

Using the Tale CLI (Recommended)

For zero-downtime blue-green deployments, install the Tale CLI (macOS / Linux):

curl -fsSL https://raw.githubusercontent.com/tale-project/tale/main/scripts/install-cli.sh | bash

Then deploy:

tale deploy

On first run, the CLI interactively configures your domain, TLS, API keys, and security secrets. See Tale CLI documentation for the full command reference.

Authentication Options

Tale supports multiple authentication methods. By default, users sign up with email/password.

Microsoft Entra ID (SSO)

Enable single sign-on with Microsoft 365 / Azure AD:

Azure setup:

1. Go to Azure Portal → Microsoft Entra ID → App registrations
2. Create a new registration (or use existing)
3. Add redirect URI: https://yourdomain.com/api/sso/callback
4. Note the Application (client) ID, Directory (tenant) ID, and create a client secret

Tale setup:

1. Go to Settings → Integrations in the Tale admin panel
2. Select Microsoft Entra ID as the SSO provider
3. Enter your client ID, client secret, and issuer URL
4. Optionally enable group sync, role mapping, auto-provisioning, and OneDrive access

Trusted Headers Authentication

For deployments behind an authenticating reverse proxy (e.g., Authelia, Authentik, oauth2-proxy):

# Add to .env
TRUSTED_HEADERS_ENABLED=true
TRUSTED_EMAIL_HEADER=X-Auth-Email      # optional, default shown
TRUSTED_NAME_HEADER=X-Auth-Name        # optional, default shown
TRUSTED_ROLE_HEADER=X-Auth-Role        # optional, default shown
TRUSTED_TEAMS_HEADER=X-Auth-Teams      # optional, default shown

Your proxy must send these headers with every request:

• X-Auth-Email: User's email address
• X-Auth-Name: User's display name
• X-Auth-Role: One of admin, developer, editor, or member
• X-Auth-Teams (optional): Comma-separated list of teams in id:name format (e.g., abc123:Engineering, def456:Design). The external IdP is the single source of truth - team IDs are passed through directly without any internal database lookup. Omit the header to leave teams unchanged, send empty to remove from all teams.

⚠️ Security: Only enable this when Tale is behind a trusted proxy that strips these headers from external requests.

Updating Tale

Using the Tale CLI (Recommended for Production)

# Deploy with interactive version selection
tale deploy

# Or deploy a specific version
tale deploy v1.0.0

# Check current deployment status
tale status

# Rollback to the previous version if needed
tale rollback

See Zero-Downtime Deployment and Tale CLI documentation for details.

From Source (Development)

git pull
docker compose down
docker compose up --build -d

Essential Commands

Local Development

docker compose up --build        # Start Tale
docker compose down              # Stop Tale (keeps data)
docker compose logs -f           # View logs
docker compose down -v           # Fresh start (deletes all data)

Production (Tale CLI)

tale deploy                      # Deploy (interactive version selection)
tale status                      # Show deployment status
tale logs platform --follow      # View service logs
tale rollback                    # Rollback to previous version
tale cleanup                     # Remove inactive containers

Convex Dashboard Access

To view backend data, logs, and manage environment variables, you'll need an admin key:

./scripts/get-admin-key.sh

The script will display the dashboard URL, deployment URL, and admin key. Follow the instructions shown to log in.

The admin key is required every time you open the dashboard. Keep it secure—anyone with this key has full access to your backend.

Monitoring & Metrics

Every Tale service exposes Prometheus metrics. Access is gated by a single bearer token—set it to enable scraping:

# Add to .env
METRICS_BEARER_TOKEN=your-secret-token-here

When the token is unset, all /metrics/* endpoints return 404.

Available endpoints

Endpoint	Service	Metrics
/metrics/crawler	Crawler (Python)	HTTP request count & latency, process stats
/metrics/rag	RAG (Python)	HTTP request count & latency, process stats
/metrics/operator	Operator (Python)	HTTP request count & latency, process stats
/metrics/platform	Platform (Bun)	Event loop lag, heap, GC, CPU, memory
/metrics/convex	Convex backend	261 built-in metrics (query/mutation latency, UDF execution, DB ops)

Prometheus scrape config

scrape_configs:
  - job_name: tale-crawler
    scheme: https
    metrics_path: /metrics/crawler
    authorization:
      credentials: your-secret-token-here
    static_configs:
      - targets: ['your-tale-host.com']

  # Repeat for: tale-rag, tale-operator, tale-platform, tale-convex
  # changing metrics_path accordingly

Development

For local development (non-Docker):

Prerequisites

• Bun: 1.3.x or higher (installation instructions)
• Python: 3.12.x (required for Python services: rag, crawler)
• uv: Python package manager (installation instructions)

Install uv (Python package manager)

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Note: Python services are configured to use Python 3.12 via .python-version files. When you run uv sync in these directories, uv will automatically use the correct Python version.

Development Commands

# Install dependencies
bun install

# Install Python dev dependencies (optional, required for linting/testing Python services)
cd services/rag && uv sync --extra dev
cd ../crawler && uv sync --extra dev
cd ../..

# Type checking
bun run typecheck

# Linting
bun run lint
bun run lint:fix

# Build all services
bun run build

# Run tests
bun run test
bun run test:watch
bun run test:coverage

# Start development servers
bun run dev

Known Issues

• xlsx security vulnerability: The project uses xlsx@0.18.5 which has known security vulnerabilities (Prototype Pollution and ReDoS). This is the latest version available and no fix is currently released. The package is used for Excel file parsing in the documents feature. Consider the risk based on your use case.

• ENVIRONMENT_FALLBACK warning: During platform build, you may see an ENVIRONMENT_FALLBACK error. This is a Convex-specific warning and doesn't prevent successful builds.

Documentation

User Guides

• Chat Agent Guide - Learn how to use the AI-powered chat assistant to manage customers, automate workflows, and access your business data through natural conversation
• Workflow Guide - Build powerful automation workflows with AI, data processing, and customer engagement

Administration

• Role-Based Access Control - User roles and permission system

Operations

• Tale CLI - CLI tool for production deployment, management, and zero-downtime updates
• Zero-Downtime Deployment - Blue-green deployment strategy details
• Monitoring & Metrics - Prometheus endpoints and scrape configuration

Need Help?

• Logs (dev): docker compose logs -f to see what's happening
• Logs (production): tale logs <service> to view service logs
• Health checks: Visit {SITE_URL}/api/health
• Deployment status: tale status to check production deployment
• Convex Dashboard: Generate admin key (see above) for backend data and logs
• Detailed docs: Check services/*/README.md for each component and tools/cli/README.md for CLI reference

---

Ready to build? Start exploring at your configured domain!

Star History