Skip to content

README.md

Latest commit

 

History

History
202 lines (139 loc) · 9.35 KB

README.md

File metadata and controls

202 lines (139 loc) · 9.35 KB

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.

Quick start

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.

1. Install the CLI

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

2. Create a project

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.

3. Start Tale

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 Quick start guide.

What can you do?

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.

Command reference

Development

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

Production

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

Upgrading from v0.2.x → v0.3.x (split-convex)

v0.3.0 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.

Deploy to production

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.

Authentication options

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)

Development

For local development (non-Docker):

Prerequisites

Development commands

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

Optional: hybrid mode against a containerised Convex

After the v0.3.0 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

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

  • AI-assisted development — Use AI-powered editors to create agents, workflows, and integrations
  • AI Chat — Use the AI chat assistant to explore data, attach files, and select agents
  • Knowledge Base — Manage documents, websites, products, customers, and vendors
  • Conversations — Manage customer conversations from a unified inbox
  • Automations — Build multi-step workflows with triggers, conditions, loops, and AI steps
  • Agents — Create specialized AI assistants with custom instructions and tools

Administration

  • Roles and Permissions — User roles, permission matrix, and SSO configuration
  • Authentication — Email/password, Microsoft Entra ID SSO, and trusted headers
  • Settings — Organization settings, teams, integrations, branding, and API keys

Operations

Need help?

  • 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

Star history

Star History Chart