Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mistle.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The easiest way to get Mistle up and running is to use Docker Compose.

​
Prerequisites

  • Docker Desktop or Docker Engine
  • Docker Compose V2
  • Network access for image pulls

​
Quick Start

Choose one of these two entry points:
  1. Recommended: from remote installer (no repository checkout required):
curl -fsSL https://raw.githubusercontent.com/mistlehq/mistle/main/deploy/compose/local/install.sh | sh
  1. Alternative: from a source checkout (recommended for contributors/workflow customization):
git clone [email protected]:mistlehq/mistle.git
cd ./mistle/deploy/compose/local
./up.sh
The installer fetches compose assets into ~/.mistle/local, preserves an existing .env, and starts the stack by executing ./up.sh. If you use the source checkout path, keep local changes in .env and .generated/runtime.env. If you use the installer, keep your working files under ~/.mistle/local.

​
What ./up.sh does

  • creates .env from .env.example when missing
  • validates required values such as MISTLE_DOCKER_IMAGE and MISTLE_SANDBOX_DEFAULT_BASE_IMAGE
  • writes a per-run ./.generated/runtime.env and starts Compose services
  • starts base infra (postgres, valkey, seaweedfs, mailpit) first
  • ensures the local object-store bucket exists
  • starts the mistle service
  • sets callback behavior:
    • if MISTLE_SERVICES_CONTROL_PLANE_API_PUBLIC_URL is blank, it starts a Cloudflare tunnel for an ephemeral public callback URL
    • if set, that static URL is used

​
Open the stack

  • Dashboard: http://localhost:3000
  • Control Plane API: http://localhost:5100
  • Data Plane Gateway: http://localhost:5202
  • Tokenizer Proxy: http://localhost:5205
  • Mailpit UI: http://localhost:8025

​
Verify your run

  1. Open the dashboard URL and complete authentication.
  2. Confirm health endpoints:
curl http://localhost:3000
curl http://localhost:5100/__healthz
curl http://localhost:5202/__healthz
curl http://localhost:5205/__healthz
  1. If you cloned the repository locally, run the local smoke test:
pnpm compose:local:smoke-test -- --restart-check

​
Stop and cleanup

When you want to stop the local stack: 
cd ~/.mistle/local
./down.sh
If you are running from source checkout, use deploy/compose/local instead of ~/.mistle/local. To remove local data as well: 
cd ~/.mistle/local
./down.sh -v

​
Public callback URLs

Provider callbacks and webhooks need a publicly reachable control-plane URL. That value is MISTLE_SERVICES_CONTROL_PLANE_API_PUBLIC_URL (or the generated quick-tunnel URL in local .generated/runtime.env). Use Webhook and Callback URLs when configuring provider registrations.

​
Next steps