Run the Engine

The Engine is a single process that serves the dashboard, the SDK and OpenTelemetry endpoints, and the GraphQL and MCP APIs.

What you need

A Threadify license. Get one when you sign up.
A PostgreSQL database, and credentials that can create tables in it.
A hash-chain secret. Generate it once with openssl rand -hex 32 and store it somewhere safe. Threadify uses it to sign history, so you need the same value every time the Engine starts.

On Linux and macOS the Engine starts its own Valkey and NATS, so there’s nothing else to install. On Windows, point it at an existing Redis or Valkey server (see External Redis or Valkey).

Install

curl -fsSL --proto '=https' --proto-redir '=https' \
  https://github.com/ThreadifyDev/engine/releases/latest/download/install.sh \
  -o install.sh
sh install.sh
export PATH="$HOME/.local/bin:$PATH"

The installer checks the download’s checksum, installs the threadify binary, and writes a config.yaml template. It never overwrites a config file you’ve already edited, and it doesn’t start the Engine. Releases are available for macOS (ARM64), Linux (AMD64) and Windows (AMD64, using Git Bash).

Configure

Edit the installed template, or save this as config.yaml:

license_key: "$THREADIFY_LICENSE_KEY"

server:
  host: "0.0.0.0"
  port: 8081
  public_url: "http://localhost:8081"
  browser_origin: "http://localhost:8081"

postgres:
  url: "$POSTGRES_URL"
  max_connections: 25
  max_idle_connections: 5

security:
  hash_chain_secrets:
    v1: "$HASH_CHAIN_SECRET_V1"
  hash_chain_current_version: "v1"

logging:
  level: info

Values that start with $ are read from the environment. Set them and start the Engine:

export THREADIFY_LICENSE_KEY='your-license-key'
export POSTGRES_URL='postgres://USER:PASSWORD@localhost:5432/threadify?sslmode=disable'
export HASH_CHAIN_SECRET_V1='your-saved-secret'
threadify --config ./config.yaml

For a remote database, use your provider’s TLS settings (for example sslmode=require) instead of sslmode=disable.

Configuration files from earlier releases keep working. You don’t need to change them to upgrade.

If you don’t pass --config, the Engine uses CONFIG_PATH, then looks for config/config.yaml relative to where it’s started. Pass --config explicitly in service definitions so the Engine always finds the same file.

Run with Docker

The image includes the same template at /app/config/config.yaml, already wired to these environment variables. Create threadify.env:

THREADIFY_LICENSE_KEY=your-license-key
POSTGRES_URL=postgres://USER:PASSWORD@DATABASE_HOST:5432/threadify?sslmode=require
HASH_CHAIN_SECRET_V1=your-saved-secret
THREADIFY_PUBLIC_URL=https://threadify.example.com
THREADIFY_BROWSER_ORIGIN=https://threadify.example.com

docker volume create threadify-data
docker run -d --name threadify --restart unless-stopped \
  --env-file ./threadify.env \
  -p 8081:8081 \
  -v threadify-data:/data \
  ghcr.io/threadifydev/engine:latest

Pin a version tag instead of latest so upgrades happen when you choose.
The image is built for Linux AMD64.
Inside a container, localhost means the container itself. Use a hostname the container can reach for your database.
To use your own config file, mount it at /app/config/config.yaml.
The image runs as UID/GID 65532. Bind-mounted directories must be writable by that user.

Put it behind HTTPS

Locally, open http://localhost:8081. For a shared deployment:

Route your HTTPS hostname to the Engine port. Serve it at the root of the hostname (not under a path), and forward WebSocket upgrades.
Set both server.public_url and server.browser_origin to that address, for example https://threadify.example.com.

browser_origin must exactly match the address people type into their browser, or browser sign-in will fail. Locally, pick either localhost or 127.0.0.1 and use it consistently; browsers treat them as different sites. Administrators can change the public URL later in Settings → Engine. That change applies immediately. Changes to config.yaml need a restart.

Keep your data

The Engine keeps live run state in Valkey and history in PostgreSQL. Back up PostgreSQL as you normally would, and keep the Engine’s data directories on persistent storage:

Install	Location
Binary	`data/valkey` and `data/jetstream`, next to the binary
Docker	`/data` (the `threadify-data` volume above)

Losing the Valkey data loses runs that are in progress and any outstanding execution grants. Keep your hash-chain secret too. When you rotate it, add a new version (v2) and switch hash_chain_current_version, but keep the old one in the config. Older history can only be verified with the secret it was signed with.

External Redis or Valkey

redis:
  url: "rediss://default:URL_ENCODED_PASSWORD@redis.example.com:6379/0"

You can also set REDIS_URL. Use rediss:// for TLS and redis:// without it, and URL-encode special characters in the password.

Running more than one Engine

Replicas must share the same PostgreSQL database, the same Redis/Valkey server, and an external NATS server. Engines that each start their own NATS don’t share work, so don’t run replicas with the built-in broker.

nats:
  mode: external
  url: "nats://nats.example.com:4222"

Provide NATS authentication and TLS through your NATS deployment. You can also split the HTTP service from the background persistence workers with threadify --mode engine and threadify --mode writer. Both need external NATS.

Optional AI agent

The Engine includes an AI assistant for the dashboard. It’s off unless you start the Engine with --with-agent and configure a model. See AI assistant.

Check it’s running

curl --fail http://localhost:8081/health
threadify --config ./config.yaml --healthcheck
threadify --version

Then sign in and create an API key. A healthy Engine can still reject requests once your plan’s allowance is used up. See Plans and limits.

Get started

Concepts

Contracts

SDKs

Integrations

Operate

GraphQL API

What you need

Install

Configure

Run with Docker

Put it behind HTTPS

Keep your data

External Redis or Valkey

Running more than one Engine

Optional AI agent

Check it’s running