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 does several things:

• Checks prerequisites
• Generates .env
• Starts the stack
• Connects your reverse proxy
• Verifies the first sign-in

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. 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. AWS users can use the included Terraform modules.

Choose an authentication mode

WATCHER_AUTH_MODE selects who handles sign-in:

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 sign-in:

• 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. 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 page. It contains these items:

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

Verify it as described under Supply chain security.

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.

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

Use true or false. The setting is read when the process starts. Restart the affected servers or jobs after changing it. An explicit false keeps the setting disabled across upgrades. In Compose, an empty value counts as unset and resolves to true.

For a new installation with an empty database, keep the default. For an existing database, every API replica and ingestion job that shares it must support this setting before it is enabled. Server release 0.34.0 is the first compatible release.

If you already run 0.34.0 or later with the setting unset, the first deploy of a release with the true default activates it. Before that deploy, verify every writer and any workload or automation that could restart an old image. Take a database backup before that deploy too. Alternatively, set an explicit false before deploying to defer activation, then follow the two stages below.

When upgrading from pre-0.34.0 code, explicitly set false on every writer for the first compatible rollout. This includes skipping versions to a release that defaults to true. Replace all old writers. Also update any workload or automation that could restart an old image. Once all writers are compatible, back up the database, then set true and redeploy as a separate step. Follow Update Watcher and the release upgrade steps.

Enabling the setting does not change existing sessions or repair earlier collisions. Once sessions have been created with it enabled, setting it to false does not make older server code safe to use. Roll back only to compatible code, or restore the pre-activation database backup and its matching release. Restoring a backup discards writes made after it was taken.

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 sign-in.
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 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.