AI assistant

The Engine includes an AI assistant that can read threads, explain what happened and help you write contracts. It’s off until you turn it on. It works with Ollama and with any gateway that supports OpenAI-compatible Chat Completions with streaming and function calling. You don’t need an OpenAI account.

Turn it on

Add a model to your Engine’s config.yaml (see below).
Start the Engine with --with-agent:
threadify serve --config ./config.yaml --with-agent
With Docker, add serve --with-agent after the image name.

The first start downloads the assistant’s runtime and checks it against the release. Later starts reuse it. With Docker, it’s stored in /data/agent, so keep /data on a volume. If the assistant can’t start or becomes unavailable, the dashboard shows a retry message and everything else keeps working.

Choose a model

Add one of these to config.yaml, alongside your existing settings.

Ollama

ai:
  enabled: true
  gateway:
    base_url: http://127.0.0.1:11434/v1
    model: your-installed-model

Use the exact name of a model you’ve pulled, and choose one that supports tool calls. A local model keeps everything on your machine; a cloud model sends requests to its provider.

A gateway with an API key

ai:
  enabled: true
  gateway:
    base_url: https://ai.example.com/v1
    model: your-model-id
    api_key_env: THREADIFY_AI_GATEWAY_KEY

Set THREADIFY_AI_GATEWAY_KEY in the Engine’s environment, from your service manager or secret store. If your gateway doesn’t need a key, leave out api_key_env.

A gateway with certificates

ai:
  enabled: true
  gateway:
    base_url: https://ai.internal.example.com/v1
    model: your-model-id
    tls:
      ca_file: certs/gateway-ca.pem
      cert_file: certs/client.pem
      key_file: certs/client-key.pem

You need	Set
To trust a private CA	`ca_file`
A client certificate (mTLS)	`cert_file` and `key_file`
Neither (a public HTTPS gateway)	Leave out `tls`

Files must be PEM, and the private key must not be encrypted. Relative paths are relative to config.yaml. You can combine tls with api_key_env.

Rules

base_url includes the API prefix, usually /v1, but not /chat/completions.
model is the gateway’s exact model ID.
If api_key_env is set, that variable must not be empty.
Your Threadify license is never sent to your gateway.
The Engine doesn’t follow redirects or use HTTP proxy environment variables when calling the gateway.
Restart the Engine after changing these settings or rotating keys or certificates.

In a container, use paths inside the container for the config and certificates, and remember that 127.0.0.1 is the container itself. To reach Ollama on the host, use a hostname the container can resolve.

Conversations

Conversations live in the assistant’s memory and are lost when the Engine restarts. Anything the assistant saved, such as a contract, stays in Threadify. If you run several Engines behind a load balancer, use sticky sessions so each conversation keeps talking to the same Engine. What you type, and the data the assistant reads to answer you, is sent to the model you configured.

Run it on a separate server

To run the assistant as its own service, start the Engine without --with-agent and point it at the assistant:

ai:
  agent:
    url: https://agent.example.com

You can also set THREADIFY_AGENT_URL. Use the base address only, with no path. Configure the model on the assistant’s server; the Engine doesn’t pass model keys or certificates to it. You can use --with-agent or ai.agent.url, not both. ai.enabled: false turns the assistant off completely.

Install without internet access

Download the runtime in advance:

threadify agent install-runtime --agent-cache-dir /var/lib/threadify/agent
threadify serve --config ./config.yaml --with-agent --agent-cache-dir /var/lib/threadify/agent

On a machine with no internet access, copy the runtime archive for your platform from the same Engine release and add --agent-runtime-archive /path/to/runtime.tar.gz to the install command. You can set the cache directory with THREADIFY_AGENT_CACHE_DIR instead of the flag.

Check it works

Open a thread in the dashboard and ask:

Summarize this thread’s status. Don’t change anything.

Problem	Check
No AI features in the dashboard	The Engine was started with `--with-agent`, or `ai.agent.url` is set, and `ai.enabled` isn’t `false`
Connection refused	The gateway’s host and port are reachable from the Engine
HTTP 404	`base_url` ends in the API prefix, without `/chat/completions`
HTTP 401 or 403	The API key, client certificate, and the gateway’s access rules
TLS errors	The CA, hostname, expiry, file permissions, and that the certificate matches the key
Tool calls fail	The model supports function calling
Assistant unavailable	The Engine can download and write the runtime cache. If setup failed, fix the cause and restart the Engine.

Get started

Concepts

Contracts

SDKs

Integrations

Operate

GraphQL API

Turn it on

Choose a model

Ollama

A gateway with an API key

A gateway with certificates

Rules

Conversations

Run it on a separate server

Install without internet access

Check it works