tai-distribution, running the
official image. The bundle needs Docker Compose 2.20 or newer.
Boot the bundle
1
Get the bundle
2
Pin the image and set the secrets
POSTGRES_PASSWORD (it has no default — Compose refuses to start until
it is set), and pin the image to a release rather than running latest:TAI_VERSION in .env
3
Create the config directory
config/ bind-mounts at /app, so config/manifest.yml is the
manifest the runtime loads and config/.env is the
app-side environment. Create config/.env even when it is empty — the
config-reload path treats a missing file as an error.The runtime writes the settings you save from Studio or the API back into
these files, so at every start the stack hands config/ to the image’s user
(uid 1000). After the first start, reading or editing these files by hand on
the host takes that uid (sudo).4
Start it
config-init hands config/ to the image’s user,
and db-migrate runs tai db migrate; serve and backend wait for both before
they start. Only serve publishes a port
(${TAI_SERVE_PORT:-8000}) — Postgres and Redis stay on the Compose network.The persistent mounts
Three paths a real deployment must keep across a container recreation, each located by an env var the server reads:
The bundle bind-mounts
config/ for the first, mounts the tai-plugins-data
named volume at /app/plugins for the second on every app service and the
db-migrate one-shot, and backs /app/templates with the
tai-storage-local-data named volume for the third. A packaged
marketplace install refuses while TAI_PLUGINS_DIR is
unset, and every serve and backend process mounts the same directory. Persist all
three, or a recreated container loses stored files or boots with the code and its
registration out of sync. The bundled Postgres and Redis
keep their own named data volumes.
See Add plugins for the two ways a deployment installs
plugins onto these mounts.
Profiles
The core stack is arq-on-Redis, and the example manifest selects local storage (storage_module: tai42_storage_local). Four opt-in profiles add
infrastructure. celery, minio, and monitoring serve plugins that are not in
the minimal image — add the plugin (a derived image or a marketplace install) before
enabling its profile. sandbox serves the Docker sandbox provider, which the image
already ships. The core Redis is Redis 8, so the default checkpoint store and LLM store
run on it with no profile:
compose/langfuse/: Langfuse 4.x with
ClickHouse 26.4. A deployment that runs the 3.x stack moves with
Move the Langfuse stack to 4.x.
Its langfuse-web
joins the core stack’s <project>_monitoring network (tai_monitoring under the
default project name; TAI_CORE_PROJECT in compose/langfuse/.env names the core
project), so bring the core stack up first. The containers then reach it at
http://langfuse-web:3000 (inside a container, localhost is that container). Set
that address as LANGFUSE_HOST in two places:
config/.env, withLANGFUSE_PUBLIC_KEYandLANGFUSE_SECRET_KEY: the plugin’s reads..env, withOTEL_COLLECTOR_LANGFUSE_AUTH(base64 of<public key>:<secret key>): the collector’s sends.
-p), its own
LANGFUSE_WEB_PORT and its TAI_CORE_PROJECT.
The core stack owns the network. If the core stack is taken down and up again while
langfuse-web is stopped, the network it pointed at is gone and it refuses to start
(network … not found). Recreate it:
Build the image from source (dev only)
For running the stack against uncommitted local changes,compose/docker-compose.local.yml layers a SOURCE=local build onto every app
service, building from sibling checkouts instead of pulling the release:

