> ## Documentation Index
> Fetch the complete documentation index at: https://docs.threadify.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Run the Engine

> Install and configure a company-owned Threadify Engine with its embedded dashboard.

## What you need

* A Threadify-enabled license from [account signup](https://threadify.dev/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

```sh theme={null}
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`:

```yaml theme={null}
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:

```sh theme={null}
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.

<Note>
  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.
</Note>

`--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:

```dotenv theme={null}
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
```

```sh theme={null}
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.

## Public address and browser login

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](/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:

```yaml theme={null}
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](https://github.com/ThreadifyDev/engine/blob/main/threadify-go/SELF_HOSTING.md)
for external NATS and split Engine/writer modes.

## Verify startup

```sh theme={null}
curl --fail http://localhost:8081/health
threadify --config ./config.yaml --healthcheck
```

Then [sign in and create an API key](/authentication). A healthy process can
still reject traffic if its Registry allowance is exhausted; see
[plans and limits](/plans-and-limits).