Operator guide¶
This guide is for the people who install Tinfirm and keep it running. It assumes you run containers in production and know your way around Kubernetes or Docker Compose.
What you run¶
| Part | What it does |
|---|---|
| Server | One container image, ghcr.io/flowtivo/tinfirm-server, that serves the web app, the REST API and the MCP endpoints. It listens on port 8080, and on 8081 for its health probes. |
| PostgreSQL 18 | Tinfirm's only database. It also holds the queue of work, so there is no message broker. |
| LiteLLM | The model gateway. Every model call an agent makes goes through it, with the key and budget of whoever pays. It ships with the Compose stack and the Helm chart, with the model port beside it, and only the server and the model port reach it. |
| Runner hosts | Machines with Docker that run agents' turns, each in its own sandbox. A runner host connects out to the server, so it needs no inbound port. Company runner hosts are yours to run; members may connect personal ones. |
The model port serves LiteLLM's model routes alone: the server sends its model requests through it, and the company's other services can call it with LiteLLM keys of their own. One optional service ships beside the server: tinfirm-lore, which copies a Jira or Confluence scope into PostgreSQL and lets agents search it.
Choose how to install¶
| Path | Use it for |
|---|---|
| Docker Compose | Trying Tinfirm on one machine, development, or a single small host |
Helm chart tinfirm |
Production on Kubernetes, with an external PostgreSQL 18 |
Both run the same server image. Agents also need at least one runner host, however you install the server.
Moving here
The production guides still live in the repository, under docs/operations/: helm.md and external-database.md for Kubernetes, auto-deploy.md for a Compose host that deploys every commit on main, and entra-id.md for sign-in with Microsoft Entra ID. They move to this guide one by one.