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 | bashWindows (PowerShell):
irm https://raw.githubusercontent.com/tale-project/tale/main/scripts/install-cli.ps1 | iextale init my-project
cd my-projectThe 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 startVisit 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.
| Goal | How |
|---|---|
| Create custom agents | Edit JSON files in agents/ — define instructions, tools, and models |
| Build automations | Edit JSON files in workflows/ — triggers, conditions, loops, AI steps |
| Add integrations | Edit files in integrations/ — REST APIs, SQL databases, custom connectors |
| Use AI to build configs | Open the project in Claude Code, Cursor, Copilot, or Windsurf — the AI knows your schemas |
| Chat with AI assistants | Built into the platform — start chatting immediately |
| Build a knowledge base | Upload documents, crawl websites, manage products and customers |
| Manage conversations | Unified inbox for customer conversations with AI-assisted replies |
| View backend data | Run tale convex admin and open the Convex Dashboard |
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 configurationtale 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 containersSee the CLI reference for all options and flags. Pending data migrations are detected and applied automatically on the next tale start or tale deploy.
tale deployThe 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 servicesYou 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_FALLBACKerror. This is a Convex-specific warning and doesn't prevent successful builds.
The docs site ships in three locales (en, de, fr) with full coverage. The platform UI itself ships six (en, de, de-AT, de-CH, fr, fr-CH) — regional variants share the docs of their base locale. 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, guardrails (content safety, PII detection, moderation provider), 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 statusto check production deployment - Convex Dashboard:
tale convex adminto generate an admin key - Issues and discussions: github.com/tale-project/tale/issues
Read AGENTS.md before your first PR — it is the single contract for code style, security, testing, i18n, and documentation across every workspace. docs/AGENTS.md covers the Mintlify documentation site; .agents/TERMINOLOGY.md covers cross-locale translation rules. Run bun run check (format, lint, typecheck, tests) before opening a PR; the pull request template lists the rest of the pre-merge checklist.