---
description: Install self-hosted Watcher, then verify an existing update job or record an explicit automation deferral.
---

> Part of the Watcher docs. Index of all pages, with summaries: https://watcher-docs.apolloresearch.ai/llms.txt
> Before upgrading Watcher, read the release pages and full changelogs for every version crossed: https://watcher-docs.apolloresearch.ai/releases/index.md
> Found an issue with this page? Report it: https://github.com/ApolloResearch/watcher-bin/issues/new?title=Docs%20feedback%3A%20Setup&body=Page%3A%20Setup%0AURL%3A%20https%3A%2F%2Fwatcher-docs.apolloresearch.ai%2Fself-hosting%2Fsetup%2F%0A%0A

# Setup

The release bundle's `prompts/setup.md` points a coding assistant to the docs
index for your release. It finds the guides for your environment there.
For Docker Compose, the [guided setup runbook](prompts/setup.md) does several
things:

- Checks prerequisites
- Generates `.env`
- Starts the stack
- Connects your reverse proxy
- Verifies the first login

For ongoing updates, it assesses and verifies an existing reviewed deployment
job. If no suitable job is available, it records an implementation handoff and
an explicit deferral.

For Kubernetes, follow the [Helm example](kubernetes-infrastructure.md). The
steps below target Docker Compose.

## What you need

You need these items:

- A Linux host with Docker Engine and the Compose plugin
- Access to the server image registry and the image tag for your release
- A reverse proxy or load balancer that terminates TLS
- LLM API keys for the grading models you plan to use
- An authentication mode chosen before setup

The stack includes Postgres. You can use a managed database instead. The
database user needs no special attributes. It does not need superuser or
`BYPASSRLS`. It only needs ownership of an empty database. Migrations create and
own every table.

If you still need a host, network, database, or certificate, start with the
[infrastructure prerequisites prompt](prompts/prerequisites.md). AWS users can
use the included [Terraform modules](aws-infrastructure.md).

## Choose an authentication mode

`WATCHER_AUTH_MODE` selects who handles login:

| Mode | Use it when | What you provide |
| --- | --- | --- |
| `workos` | Users should sign in through your identity provider | Public hostname, allowed email domains, and the WorkOS values supplied for the deployment |
| `proxy` | An authenticating reverse proxy sits in front of Watcher | Trusted identity and role headers on every request |

### SSO mode

In `workos` mode, WorkOS brokers sign-in with your identity provider. Your
identity-provider groups decide who is an admin or member. Set these variables
before the first login:

- `WATCHER_WORKOS_CLIENT_ID`
- `WATCHER_WORKOS_API_KEY`
- `WATCHER_WORKOS_ORG_ID`

### Proxy mode

In `proxy` mode, the proxy authenticates each request. It injects identity and
role headers. The role `admin` grants access to
[organization settings](../concepts/organization-settings.md). Strip
client-supplied copies of these headers before adding trusted values.

The bundle includes a basic-auth reference proxy. It is for a small trusted team
behind an IP allowlist. It is not a hardened multi-tenant boundary.

## Get the release

Download the self-host bundle from the
[Watcher releases](https://github.com/ApolloResearch/watcher-bin/releases) page.
It contains these items:

- Compose file
- Terraform modules
- Examples
- Prompts
- Support bundle script

Verify it as described under
[Supply chain security](supply-chain.md#verify-release-files).

The guided setup runbook generates `.env` from `.env.example`. `WATCHER_IMAGE_TAG`
selects the server images.

## Distinct tool invocations

This setting keeps otherwise identical tool calls separate when their IDs
differ. It applies only to sessions created while it is enabled. Existing
sessions keep their previous matching behavior. This includes after a
[content scrub](security.md#retention-and-deletion).

| Deployment | Setting | Shipped default |
| --- | --- | --- |
| Docker Compose | `WATCHER_DISTINCT_TOOL_INVOCATIONS_ENABLED` in `.env` | `false` |
| Helm | `api.distinctToolInvocationsEnabled` in your values file | `false` |
| Custom server or ingestion job | `XYLON_DISTINCT_TOOL_INVOCATIONS_ENABLED` in the process environment | `false` when unset |

Use `true` or `false`. The setting is read when the process starts. Restart the
affected servers or jobs after changing it. The shipped defaults allow an
upgrade in two stages. First, replace every old server and ingestion job. Then
enable the setting. Follow the [release upgrade steps](../releases/index.md)
before enabling it on an existing database.

For a new installation with an empty database, set it to `true` before starting
the stack. Keep it enabled in your operator-owned configuration for later
updates.

## Run the setup

1. Unpack the verified release bundle and open its `prompts/setup.md`.
2. Paste it into a fresh coding-assistant session with access to the release
   files. Tell it you are using Docker Compose. It finds the guided setup
   runbook through the linked docs index.
3. Follow the prompts for secrets, DNS, reverse-proxy configuration, and login.
4. Supply your existing reviewed update job for assessment and verification. If
   no suitable job is available, record an implementation handoff. Record an
   explicit deferral with an owner, reason, and follow-up date. That owner
   remains responsible for manual updates until automation is enabled.

The entry links to docs for the bundle's major and minor version. Use the
supplied release files and image tag. If the assistant cannot access the docs,
provide the relevant pages from a connected machine.

Use [Automate Analyzer updates](automatic-updates.md) for implementation
guidance. Use it when a deployment job needs to be built or revised.

You can re-run the guided setup runbook to finish an interrupted installation.
Its symptom index also helps diagnose common deployment failures.