Skip to content

quickstart.md

Latest commit

 

History

History
164 lines (107 loc) · 5.01 KB

quickstart.md

File metadata and controls

164 lines (107 loc) · 5.01 KB
title Quick start
description Get Tale running locally in under 5 minutes.

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.

  1. Go to https://openrouter.ai and create a free account.
  2. Navigate to Keys in your account dashboard and generate a new API key.
  3. 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

Windows (PowerShell):

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

Or download the binary directly from GitHub Releases:

# 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

The CLI prompts for your domain, API key, and TLS mode. Security secrets (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

tale start

Wait for the ready message:

Tale Dev v0.x.x  Ready.

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

To stop all services while keeping your data:

docker compose -p tale-dev down

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

Upgrading

tale upgrade            # Upgrade CLI and sync project files

Viewing backend data

tale convex admin       # Generate admin key for the Convex Dashboard

Open /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

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

Build times vary by service (all 5 services build in ~3 minutes in parallel on a modern system). Subsequent builds are much faster thanks to Docker layer caching.

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

This mounts your local source directories into the containers so changes are reflected immediately without rebuilding images.

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

See Contributing Docker guide for more details.