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