Tale

Build AI-powered applications in minutes, not months.

Tale is a self-hosted AI platform with custom agents, a knowledge base, workflow automation, integrations, and a unified inbox. Install the CLI and run a single command to get started.

Prerequisites: Docker Desktop (v24+) and an OpenRouter API key.

Windows with Hyper-V backend: Ensure your project drive is shared in Docker Desktop Settings > Resources > File Sharing. WSL2 backend (default) requires no extra configuration.

Linux / macOS:

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

Windows (PowerShell):

irm https://raw.githubusercontent.com/tale-project/tale/main/scripts/install-cli.ps1 | iex

tale init my-project
cd my-project

The CLI prompts for your domain, API key, and TLS mode. Security secrets are generated automatically. It also generates AI editor configuration files and extracts the platform source code to .tale/reference/ so AI-powered editors can create and edit configs with full platform awareness. See AI-assisted development.

tale start

Visit https://localhost (or your configured domain) when you see "Tale Platform is running!"

Note: Your browser will show a certificate warning for self-signed certificates. This is safe to accept.

For detailed setup instructions, see the Getting started guide.

All files in agents/, workflows/, and integrations/ are live-reloaded — edit and see changes instantly.

tale init [directory]              # Create a new project with example configs
tale start                         # Start all services locally
tale start --detach                # Start in background
tale start --port 8443             # Use a custom HTTPS port
tale start --fresh                 # Re-seed builtin configs
tale upgrade                       # Upgrade CLI and sync project files
tale convex admin                  # Generate Convex dashboard admin key
tale config                        # Manage CLI configuration

tale deploy                        # Blue-green zero-downtime deployment of the current CLI version
tale status                        # Show deployment status
tale logs <service>                # View service logs
tale logs platform -f              # Follow log output
tale rollback                      # Rollback to previous version
tale cleanup                       # Remove inactive containers
tale reset --force                 # Remove all containers

v0.2.34 splits the Convex backend into its own service. Migrations are detected and applied automatically on the next tale start or tale deploy; there is no separate tale migrate command.

tale upgrade                       # Pull new CLI + images
tale start                         # Detects pending migrations, prompts to confirm
#                                  #   (non-interactive: tale deploy --yes)

The old platform-data volume is preserved so you can roll back by reverting to the previous CLI version. After verifying the new setup works, reclaim disk space with docker volume rm <projectId>_platform-data.

See the CLI reference for all options and flags.

tale deploy

The CLI handles blue-green zero-downtime deployments with automatic health checks and rollback. For full production setup including reverse proxy configuration and subpath deployment, see the Production deployment guide.

Tale uses password-based authentication by default. The first user creates the owner account; all other users are created by an admin. To enable self-service login, connect SSO or trusted headers. See the Authentication guide for full details.

• Microsoft Entra ID (SSO): Single sign-on with Microsoft 365 / Azure AD with automatic provisioning
• Trusted headers: For deployments behind an authenticating reverse proxy (Authelia, Authentik, oauth2-proxy)

For local development (non-Docker):

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

bun install                      # Install dependencies
bun run dev                      # Start development servers (spawns local Convex)
bun run typecheck                # Type checking
bun run lint                     # Linting
bun run test                     # Run tests
bun run build                    # Build all services

After the v0.2.34 split, you can run Vite locally against the dedicated convex container instead of spawning bunx convex dev:

docker compose up convex                        # in one terminal
CONVEX_EXTERNAL=true bun run dev                # in another (CONVEX_URL optional)

Useful when you want fast Vite reloads but a stable Convex backend that mirrors production. Set CONVEX_URL if your container exposes Convex on a non-default host/port.

For Python services:

cd services/rag && uv sync --extra dev
cd services/crawler && uv sync --extra dev

• 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.
• 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.

The docs are published in six locales (en, de, de-AT, de-CH, fr, fr-CH) with full coverage. Start at docs/index.md to pick an entry point by persona.

• Getting started — install Tale and open the app
• AI chat basics — chat, attach files, pick agents
• Knowledge base — documents and websites
• Conversations — customer inbox
• Approvals — review AI actions
• Your preferences — password, language, theme

• What you can build — orientation for Editors/Developers
• Create an agent — specialised AI assistants
• Workflows — multi-step automations
• Structured data — products, customers, vendors
• Integrations overview — REST, SQL, e-mail, OneDrive

• Members and roles — user management and permission matrix
• Authentication — password, SSO, trusted headers
• AI providers — configure models in the admin UI
• Governance — budgets, retention, PII detection, audit logs
• Usage analytics — time-based token and cost reporting

• Platform overview — architecture and services
• Production deployment — Docker Compose, zero-downtime deploys, reverse proxy
• Tale CLI — CLI reference
• Environment reference — all environment variables
• Operations — monitoring, error tracking, backups
• Troubleshooting — common issues

• API reference — REST API for RAG, Crawler, and Platform
• Webhooks — workflow and agent webhooks with signature verification
• AI-assisted development — configure agents/workflows in AI editors
• Contributing Docker — modify Dockerfiles and run container tests

• Logs: tale logs <service> to view service logs
• Health checks: Visit {SITE_URL}/api/health
• Deployment status: tale status to check production deployment
• Convex Dashboard: tale convex admin to generate an admin key