Skip to content

Org policy for teams

Team accounts can publish one org policy from the dashboard. The policy is a root layer above the shared team file and each machine’s local policy. Local rules can add restrictions, but cannot loosen the org policy.

  1. Sign in to the account that owns the Team license and open Org policy.
  2. Enter the policy JSON in Policy JSON, using the identifiers and expressions in the Policy file reference. Keep license keys and local file paths on the machine. Do not paste tool content or prompts.
  3. Select Publish. The dashboard lists validation errors as sentences. A successful publication shows the current version and SHA256.

The server rejects unknown fields. The published policy’s version remains 1; the publication has a separate increasing version. Publishing identical content increments the publication version while keeping the same policy hash.

flowchart TD
  A["Admin publishes<br/>in the dashboard"] --> W["Detached worker<br/>validates and caches"]
  W --> O["Org policy<br/>root layer"]
  O --> T["Shared teamPolicyFile<br/>org restrictions remain"]
  T --> L["Local policy.json<br/>org restrictions remain"]
  L --> E["Effective root<br/>and session policy"]
  E --> H["Hook reads<br/>local policy state"]
Setting Effective rule
allowedTools Intersect by matching semantics. A tool must match a regular expression in every supplied layer’s list. A missing list adds no restriction; an empty list matches nothing.
deniedTools and ethicalWall Union across the layers. Root and matching session patterns both apply.
maxCapability The most restrictive capability ceiling wins, including the selected session’s ceiling.
caps Append root and session caps. A more permissive cap does not replace a stricter one.
mode Org enforce cannot be lowered to shadow by a local file. Lower layers may tighten org shadow to enforce. License and failure state still take precedence and select shadow.
toolRules Local rules apply first, then shared team rules, then org rules. Later matching org fields are authoritative.
Actor mappings and paymentPattern Org fields win. Lower mappings cannot redirect an explicit org default matter or session mapping.

Without a published org policy, the existing shared-file behavior remains: shared top-level fields replace matching local fields. Solo ignores org cache files.

Only the detached worker makes license, seat and org-policy requests. It fetches the org policy at session start alongside license refresh, then every fifth live-session heartbeat. Heartbeats run every five minutes, so the periodic policy check is approximately every twenty five minutes.

The worker validates the published envelope and its canonical SHA256, then writes the last good copy atomically to ${PLUGIN_DATA}/org-policy.json. Hooks use local reads and do not make these requests.

A failed refresh retains the last good copy, including during the existing seven-day offline license grace, but selects shadow with a reason. An unwritable cache also selects shadow. A successful response indicating that no policy is published unbinds any retained policy.

Open Seats in the dashboard to label a registration or revoke it. Labels are admin-supplied text, at most 40 characters, stored on the server and never sent to the machine. Display IDs use the first eight fingerprint characters. There is no reported hostname.

A revoked registration receives revoked: true on its next heartbeat. The worker selects shadow with reason seat_revoked. Revocation does not deny tool calls and is not a remote kill switch. A revoked registration does not consume active seat capacity.

Revocation is reversible in the dashboard. A later successful heartbeat with explicit revoked: false permits restoration, subject to the other license and org checks. A failed request cannot clear known revocation.

Use Invite a teammate in the Seats panel. The invitation names the inviting account and sends the existing org key. The owner plus unique invitations cannot exceed the seat limit; duplicate addresses are refused with a sentence.

Invites share the org license key. A shared key cannot identify who accepted an invite. Pending invites show the address and confirmed sent date, not an invented acceptance status.

The server stores the admin-authored policy, its version and hash, seat identifiers, admin labels, invite addresses and sent dates, and each seat’s last reported policy hash. Local policy files are not uploaded.

AgentGuard’s server is a control plane for policy, not data. It stores the policy your admin writes, which seats are licensed, and which policy version each seat last reported. It never receives a tool call, a prompt, a file, or a receipt.