This guide walks you through getting Tale running locally for the first time using the Tale CLI.
Prerequisites
| Software | Minimum version | Where to get it |
|---|
| Docker Desktop | 24.0+ | https://www.docker.com/products/docker-desktop |
Get an API key
Tale uses OpenRouter as its default AI gateway, which gives you access to hundreds of models through a single API key.
- Go to https://openrouter.ai and create a free account.
- Navigate to Keys in your account dashboard and generate a new API key.
- Copy the key. You will need it during setup.
Tip: You can use any OpenAI-compatible provider, including a local Ollama instance. OpenRouter is the recommended default for its model variety and simple pricing.
Setup
Step 1: Install the CLI
Linux / macOS:
curl -fsSL https://raw.githubusercontent.com/tale-project/tale/main/scripts/install-cli.sh | bash
irm https://raw.githubusercontent.com/tale-project/tale/main/scripts/install-cli.ps1 | iex
# Linux
curl -fsSL https://github.com/tale-project/tale/releases/latest/download/tale_linux \
-o /usr/local/bin/tale
chmod +x /usr/local/bin/tale
Step 2: Create a project
tale init my-project
cd my-project
BETTER_AUTH_SECRET, ENCRYPTION_SECRET_HEX) are generated automatically.
Tip: The CLI also generates configuration files for AI-powered editors (Claude Code, Cursor, GitHub Copilot, Windsurf) and extracts the full platform source code to .tale/reference/. Open your project in any of these editors to create and edit agents, workflows, and integrations by describing what you want in natural language. See AI-assisted development for details.
Step 3: Start Tale
Wait for the ready message:
Note: The version number will vary. You will see a stream of health check messages while services are starting. Those are normal. Wait for the “Ready” message before opening your browser.
Step 4: Open the app
Go to https://localhost (or your configured domain) in your browser. The first time you open it, you will be taken to a sign-up page to create your admin account.
Daily workflow
Starting and stopping
tale start # Start all services
tale start --detach # Start in background
docker compose -p tale-dev down
-p tale-dev flag is required because tale start creates a compose project named tale-dev rather than using a standard docker-compose.yml file.
Important: Never run docker compose -p tale-dev down -v. The -v flag deletes all Docker volumes, which permanently erases your database, uploaded documents, crawler state, and all platform data. There is no recovery from this.
Updating
tale update # Update project files to match CLI version
Viewing backend data
tale convex admin # Generate admin key for the Convex Dashboard
/convex-dashboard in your browser and paste the key to inspect the database, view function logs, and manage background jobs.
Alternative: build from source
If you want to contribute to Tale or customize the platform code, you can run from source instead of using pre-built images.
git clone https://github.com/tale-project/tale.git
cd tale
cp .env.example .env
.env and fill in the required values:
| Variable | How to fill it in |
|---|
BETTER_AUTH_SECRET | Generate with: openssl rand -base64 32 |
ENCRYPTION_SECRET_HEX | Generate with: openssl rand -hex 32 |
DB_PASSWORD | Choose any password for the local database |
Important: The .env.example file ships with example secrets that must be replaced before starting.
Then build and start:
docker compose up --build
Local development with hot-reload
For a faster edit-reload cycle during development, use the development override:
docker compose -f compose.yml -f compose.dev.yml up --build
Running container tests
After modifying Dockerfiles or dependencies, validate your changes:
# Smoke test: build, start, health check, tear down
bun run docker:test
# Image validation: OCI labels, secrets, size budgets
bun run docker:test:image
# Vulnerability scan (requires trivy installed)
bun run docker:test:vulnerability
Last modified on April 7, 2026
