Run the Engine

What you need

A Threadify-enabled license from account signup.
A PostgreSQL database and credentials with permission to initialize its schema.
A persistent hash-chain secret, generated once with openssl rand -hex 32.

The Engine includes the dashboard. Linux/macOS release installations start managed Valkey and embedded NATS automatically. Windows installations need an external Redis/Valkey server. You do not need the old separate Threadify Web API.

Install a release binary

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 verifies the archive checksum and preserves existing config files. It prints the configuration path and start command; it does not start a service. Release archives support macOS ARM64, Linux AMD64, and Windows AMD64 (Git Bash).

Configure

Use the installed template or save this as config.yaml:

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

registry:
  license_key: "$THREADIFY_LICENSE_KEY"
  browser_origin: "http://localhost:8081"

auth_provider: registry

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

Supply the variables through your shell, container, or service manager:

export THREADIFY_LICENSE_KEY='YOUR_REGISTRY_LICENSE'
export POSTGRES_URL='postgres://USER:PASSWORD@localhost:5432/threadify?sslmode=disable'
export HASH_CHAIN_SECRET_V1='YOUR_SAVED_SECRET'
threadify --config ./config.yaml

The PostgreSQL example is for a local database; use your database provider’s TLS settings for remote connections. Preserve the hash-chain secret across restarts and retain previous secret versions after rotation.

The current Engine source no longer loads or ships subscription.yaml. Older releases, including v1.1.2, still require it beside the config. Keep the file when running those versions; upgrade to a release containing the removal before deleting it. Plan limits come from Registry in either case.

--config overrides CONFIG_PATH. Without either, the binary searches ./config, ../../config, then ../../../config relative to its working directory. Prefer an explicit path in service definitions.

Docker

The release image includes a configuration template at /app/config/config.yaml. Create threadify.env with your license, database URL, and saved secret:

THREADIFY_LICENSE_KEY=YOUR_REGISTRY_LICENSE
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 release tag for controlled upgrades. The current release image targets Linux AMD64. The database hostname must be reachable from inside the container; localhost inside a container refers to that container. To replace the bundled config, mount your file at /app/config/config.yaml. The image runs as UID/GID 65532, so bind-mounted data directories must be writable by that user. Open http://localhost:8081 locally. For deployment, forward your HTTPS hostname root to the Engine, including WebSocket upgrades. Set registry.browser_origin and server.public_url to that HTTPS address. These settings do not configure DNS or TLS themselves. See authentication. The standard Registry URL is built into the Engine. THREADIFY_REGISTRY_URL is an override for local testing. The homepage’s BACKEND_URL configures the homepage server, not the Engine.

Persistence and replicas

Binary installs default to data/valkey and data/jetstream beside the executable. Docker stores both under /data. Preserve those directories and PostgreSQL: Valkey contains live contract state and invocation claims; the PostgreSQL archive can lag behind that state. For an external Redis/Valkey server:

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

REDIS_URL is also supported. Use redis:// without TLS or rediss:// with TLS; URL-encode reserved characters in credentials. Separate host, port, password, and db fields are no longer supported. Replicas must share the same database, live Valkey state, and external NATS infrastructure. Independently embedded brokers are not a shared cluster. See the deployment reference for external NATS and split Engine/writer modes.

Verify startup

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

Then sign in and create an API key. A healthy process can still reject traffic if its Registry allowance is exhausted; see plans and limits.

Getting Started

Core Concepts

Integrity and access

API Reference

What you need

Install a release binary

Configure

Docker

Persistence and replicas

Verify startup

​What you need

​Install a release binary

​Configure

​Docker

​Public address and browser login

​Persistence and replicas

​Verify startup

What you need

Install a release binary

Configure

Docker

Public address and browser login

Persistence and replicas

Verify startup