--- description: >- Configure Watcher organization settings, data retention, client policies, and Slack notifications in Analyzer. --- > 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%20Organization%20settings&body=Page%3A%20Organization%20settings%0AURL%3A%20https%3A%2F%2Fwatcher-docs.apolloresearch.ai%2Fconcepts%2Forganization-settings%2F%0A%0A # Organization settings Organization settings are the org-wide configuration of your Watcher deployment. You manage them on the [Analyzer](analyzer.md)'s Organization page. They are server-side and apply to everyone in the organization. Client behavior resolves on each developer's machine instead. This includes [blocking review](blocking-and-trailing-review.md) thresholds and enforcement mode. You set these in the [Watcher client](../client/index.md)'s settings. Admins can distribute and lock those centrally too. Use [managed client settings](#managed-client-settings) below. The Organization page is visible only to users allowed to read organization settings. Only users with the admin role can edit them. Other members do not see the page. How a user gets the admin role depends on your deployment's authentication mode. In proxy mode it comes from the role header your reverse proxy injects. In WorkOS-backed SSO mode it comes from the role assigned to the member. ## Settings - **Display name.** The organization name shown across the dashboard and in notifications. - **Flag threshold.** [Sessions](sessions-and-trajectories.md) scored at or above this number are flagged for review. The default is 7. A session is flagged when any numeric score in one of its grades reaches the threshold. Blocking-review decisions whose score reaches it are alerted on as well. - **Slack notifications.** An on/off toggle plus an incoming-webhook URL. This is for the channel that receives flag alerts. When a session is flagged, Watcher sends at most one notification for it. The notification carries the [grader](graders.md)'s summary, the flagged scores, and a link back to your Analyzer. It does not include the session transcript. Flagged blocking-review decisions are alerted individually as they happen. Each alert also includes the permission request that was under review. This is the tool name, its arguments, and the working directory. Before sending, Watcher replaces credentials it recognizes in the summary, its title, and the permission request with `[REDACTED]`. It recognizes common formats, such as provider API keys, bearer tokens, passwords in URLs, private keys, and values assigned to secret-named variables. A secret in another format can still appear. Redaction applies only to the message sent to Slack. Stored grades and transcripts keep the original text, and so does the copy of the notification title and summary that Watcher stores with the session. The webhook URL is write-only. After saving, the page shows only that a webhook is configured and the URL's last four characters. The URL must use `https://`. It must not include a username or a port. Notifications are sent only when the toggle is on and a webhook is configured. ### Deployment-managed Slack webhook A self-hosted deployment can supply the Slack webhook URL itself by setting the `SLACK_WEBHOOK_URL` environment variable on the Watcher API, instead of an admin saving one in organization settings. Where to set it depends on how the deployment runs: it is the `WATCHER_SLACK_WEBHOOK_URL` entry in `.env` for the Docker Compose bundle (applied with `docker compose up -d xylon-api`, since a plain restart keeps the old value) and the `SLACK_WEBHOOK_URL` key of the Kubernetes Secret the chart reads. It is a self-hosting setting: Watcher Cloud never sets it. When it is set: - It takes precedence over the URL saved in organization settings, which is not consulted at all (it stays stored, and applies again if the variable is removed). - The destination is fixed by the deployment. While the variable is set, it cannot be changed from the Analyzer, so use it when the deployment, rather than an admin, should own where alerts land. - The webhook URL becomes read only. Organization settings report that the webhook is managed by the deployment and show the last four characters of the deployment's URL, and requests that try to change or clear the URL are rejected. - The on/off toggle and the flag threshold stay in organization settings, so turning notifications off there still sends nothing. - The destination may be an internal address, such as a relay in your network that forwards to Slack. A URL saved in organization settings must resolve to a public address; this variable is set by whoever deploys Watcher, so it is not held to that. It must use `https://` or `http://`, with no username and no port (an explicit `:443` counts as a port). An `https://` destination has its certificate verified on every send against the public roots the API image ships, so the relay needs a publicly trusted certificate. If the API runs behind an egress proxy (`HTTPS_PROXY`), list the relay in `NO_PROXY` or the POST goes through the proxy. A failed handshake or connection is logged on the API as `Slack webhook request failed` and nothing is delivered. - `http://` is accepted for a relay on a trusted network that does not terminate TLS, and it is the weaker choice. It sends the notification, and the webhook URL itself, in cleartext with no certificate verification. The URL's path is the credential that lets anyone holding it post to the channel, so anything that can observe the traffic can take the destination over. Use `http://` only on a network you trust to carry both, and prefer `https://` everywhere else. The API logs a warning at startup naming the scheme and host, never the path. This applies to this variable only: a URL saved in organization settings must still use `https://`. - The API refuses to start on a value that breaks those rules, so the mistake surfaces at deploy time rather than as alerts that never arrive. Watcher never falls back to the URL saved in organization settings, because that would send your alerts to a destination the deployment did not choose. - The last four characters of the URL are visible to every admin, so that they can tell which destination is in effect. ## Data retention The Data Retention tab controls how long Watcher stores session content. By default, automatic retention is disabled. Session content is retained indefinitely. Turn on **Scrub inactive sessions** and set a retention period between 7 and 365 days. Watcher then removes content from any session whose latest recorded activity is older than that period. Turning the policy off retains future session content indefinitely. It does not restore content that has already been scrubbed. **Scrub one session** removes the stored messages and tool-call content for a specific session. This requires confirmation. The session record, historical activity, message count, and trajectory grades remain available. See [Retention and deletion](../self-hosting/security.md#retention-and-deletion) for the complete data lifecycle. The same controls are available through the HTTP API. Set or disable automatic retention with `PATCH /api/v1/organization/settings`: ```json { "session_content_retention_days": 30 } ``` Set `session_content_retention_days` to `null` to disable the policy. Scrub one session with `DELETE /api/v1/sessions/{session_id}/content`. ## Managed client settings The Managed Settings page lets admins author the organization's [Watcher client](../client/index.md) configuration once. They can distribute it to every developer machine. The document is a YAML overlay on the client's built-in defaults. It can carry client review settings. For example, which [graders](graders.md) run at each stage of [blocking review](blocking-and-trailing-review.md). It can also include tool thresholds, command rules, and the enforcement mode. Trailing review runs on the server. It is not configured by this document. [Gateway hooks](../api/hooks.md) also resolve this saved document on the server. This includes its enforcement mode. Distribution to developer machines does not affect this. Every save is kept as a new version. How a save reaches machines is the page's "Distribute via Watcher" toggle. This is inside its "Advanced settings" section. Two options: - **Toggle on** (the default for new organizations). Each running client pulls the saved document every few minutes. It installs it as the machine's admin settings baseline. Saving is what rolls a change out. Review the document before you save it. - **Toggle off**. Watcher distributes nothing. Ship the saved YAML to `~/.apollo_monitor/settings.yaml` on each machine with your MDM tooling instead. The document works identically however it is delivered. Organizations that predate this default keep the setting they already have. An organization that has been distributing through an MDM stays that way. Turning the toggle on hands the whole fleet the document currently saved. Read it first. Until an organization saves its first document the toggle changes nothing. With nothing to pull, clients keep the settings file they already have. Individual values can be marked locked. This prevents the developer's local settings from overriding them. Unlocked values remain local defaults the developer can change. Reading the document requires permission to read organization settings. Saving it requires write permission. The document also covers profiles. An entry in its `profiles` map carries that profile's configuration. Per-profile overrides roll out through the same single document. For example, stricter thresholds under a `focus` profile. `active_profile` picks the machine default. It can be locked to pin every machine to one profile. The example below does this with the profile it defines. Add `content_permission: locked` to an entry to lock everything that profile sets in one line. The "Active profile" control is above "Advanced settings". It sets `active_profile` directly, without editing YAML. It offers three of the four built-in profiles: Default, Human in the Loop, and Auto. The fourth, Skip Permissions, turns blocking review off, so the control leaves it out. To pin it for the organization, set `active_profile: skip-permissions` in the YAML. When the YAML pins a profile the control does not list, the page shows that profile's name instead of a choice. ```yaml version: 1 active_profile: value: focus permission: locked profiles: focus: name: Focus tool_thresholds: Bash: flag_threshold: 2 deny_threshold: 5 ``` ### Honoring .watcher-ignore files `watcher_ignore_files.enabled` decides whether clients honor [`.watcher-ignore`](../client/watcher-ignore.md) files. These files keep the sessions started in one directory from being uploaded or LLM-graded. It is off by default. No directory is excluded until you turn it on. Turning it on gives every developer on the fleet that option in the directories they work in. Sessions a marker covers are not ingested. They never appear in the [Analyzer](analyzer.md). Deterministic blocking review still applies to them. Like the enforcement mode, the switch is machine-wide and admin-only. It resolves from the machine's admin settings baseline alone. A developer cannot enable it from their own settings file or from a profile. It takes the same `value` and `permission` form as any other managed value: ```yaml watcher_ignore_files: enabled: value: true permission: locked ``` ### Red-team drill The page also offers a downloadable red-team drill. This is a prompt written for an AI assistant running on a developer's machine. It carries the document above, how it is distributed, and the settings reference. Send it to a developer who has the [client](../client/index.md) installed. Their assistant checks the install. It then works out the smallest change to that one machine. This change gets an ordinary command held for review. The assistant turns [enforcement](blocking-and-trailing-review.md#enforcement-modes) on if it is not already on. It lowers a tool's flag threshold if the organization's own is too high to hold anything ordinary. It then asks which threats the team cares about. It probes each one against the organization's real thresholds. Finally, it restores the machine. What the drill can change on a machine is bounded by the document. A setting the document locks cannot be overridden from the machine at all. The drill is written to report that rather than route around it. It names the locked key. It asks an administrator to unlock it here. Unlocking allows local overrides on every machine receiving the document. Review the fleet impact before changing the lock. If nothing can be unlocked in time, the drill runs its threat probes without the demonstration. In observe mode nothing is ever blocked. A team running one cannot see what blocking review does without turning enforcement on somewhere. The drill does that on one machine instead of the fleet. Its configuration changes are local. They are reverted at the end. The session itself is ingested. This includes the probes. It is visible in the [Analyzer](analyzer.md) like any other. Containment is instruction, not sandboxing. The prompt tells the assistant to keep every probe inside a scratch directory and to use dummy credentials. An assistant that departs from it is not prevented by Watcher. ## Members The Members tab lists the organization's users. In WorkOS-backed SSO mode, admins manage members and their roles here. In proxy mode the roster is read-only. Membership and roles are managed by your identity provider and reverse proxy. Users appear after their first sign-in. ## API keys In WorkOS-backed SSO mode, the API Keys tab is where you create and revoke the organization's API keys. These are for the [HTTP API](../api/index.md) and the [Python SDK](../api/python-sdk.md). In proxy mode there is no API Keys tab. API access is governed by your reverse proxy. Choose session permissions by what the key may write: - `sessions:ingest` uploads sessions that belong to no developer. It can also add turns to an existing conversation's session, whoever owns it, when it sends that conversation's Claude Code session ID or Codex thread ID. It cannot read any session. Treat such a key as able to append to any member's conversation whose ID it knows, and revoke it if it leaks. - `sessions:write:any` writes any session, and can attribute uploads to a developer. A `sessions:write:any` key that names no developer can append to any session. - `sessions:read:any` reads every session in the organization. See [Two recorders](sessions-and-trajectories.md#trajectories) for how a conversation's session gets its owner.