From f6f3c779aedaaad69e10fcf2c286058dd5cd270f Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Tue, 9 Jun 2026 14:32:38 +0200 Subject: [PATCH] sbx: document --include-inactive flag for sbx policy ls Inactive rules are now hidden by default when org governance is active. Document the --include-inactive flag in the monitoring page and point the concepts, local, and org policy pages to it instead of each restating the display behavior. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../ai/sandboxes/governance/concepts.md | 5 +-- .../manuals/ai/sandboxes/governance/local.md | 18 ++++++---- .../ai/sandboxes/governance/monitoring.md | 35 +++++++++++++++---- .../manuals/ai/sandboxes/governance/org.md | 7 ++-- 4 files changed, 47 insertions(+), 18 deletions(-) diff --git a/content/manuals/ai/sandboxes/governance/concepts.md b/content/manuals/ai/sandboxes/governance/concepts.md index d9e5af6533..469ec5dd7d 100644 --- a/content/manuals/ai/sandboxes/governance/concepts.md +++ b/content/manuals/ai/sandboxes/governance/concepts.md @@ -140,8 +140,9 @@ whether your organization has governance enabled: [kit-defined network rules](../customize/kits.md#control-network-access) determine what sandboxes can access. - Organization governance active: organization rules apply across all developer - machines, and local and kit-defined rules are not evaluated. They still appear - in `sbx policy ls`, but with an `inactive` status. + machines, and local and kit-defined rules are not evaluated. `sbx policy ls` + hides these inactive rules by default; see + [Monitoring](monitoring.md#showing-inactive-rules) for how to list them. When organization governance is active, a user's organization policies are evaluated together, as described in [Rule evaluation](#rule-evaluation). diff --git a/content/manuals/ai/sandboxes/governance/local.md b/content/manuals/ai/sandboxes/governance/local.md index 85ae802561..89224a8a4e 100644 --- a/content/manuals/ai/sandboxes/governance/local.md +++ b/content/manuals/ai/sandboxes/governance/local.md @@ -16,8 +16,9 @@ Local rules apply only when your organization doesn't enforce governance: - **No org governance**: local rules fully control what sandboxes can access. - **Org governance active**: the organization policy replaces local policy. Local rules are inactive, and `sbx policy allow` and `sbx policy deny` have - no effect. Local rules still appear in `sbx policy ls` with an `inactive` - status. + no effect. To list the inactive local rules, run + `sbx policy ls --include-inactive`. See + [Monitoring](monitoring.md#showing-inactive-rules). See [Organization policy](org.md) for how organization governance works. @@ -139,8 +140,9 @@ If rules you add with `sbx policy allow` or `sbx policy deny` don't change sandbox behavior, your organization likely has governance enabled. Run `sbx policy ls` to check: if the output starts with a `Governance: managed by ` header, org governance is active. When it's active, the organization policy -replaces local policy, so your rules appear with `inactive` status and have no -effect. +replaces local policy, so your rules have no effect. They're hidden from `sbx +policy ls` by default; run `sbx policy ls --include-inactive` to see them with +an `inactive` status. Organization policy can't be supplemented from your machine. To change what your sandboxes can access, ask your admin to update the organization policy in @@ -150,6 +152,8 @@ the Admin Console. If a domain remains blocked after you add a local allow rule, your organization likely enforces governance, which makes local rules inactive. Run `sbx policy -ls` to check whether org governance is active and whether your rule shows an -`inactive` status. If so, the block can only be lifted by updating the org -policy in the Admin Console or via the [API](/reference/api/ai-governance/). +ls` to check whether org governance is active; if the output starts with a +`Governance: managed by ` header, it is. Add `--include-inactive` to +confirm your rule shows an `inactive` status. If so, the block can only be +lifted by updating the org policy in the Admin Console or via the +[API](/reference/api/ai-governance/). diff --git a/content/manuals/ai/sandboxes/governance/monitoring.md b/content/manuals/ai/sandboxes/governance/monitoring.md index 1b6df7e3a6..1df88ada4c 100644 --- a/content/manuals/ai/sandboxes/governance/monitoring.md +++ b/content/manuals/ai/sandboxes/governance/monitoring.md @@ -33,8 +33,10 @@ The columns are: the named sandbox. `remote` means the rule was set by your organization. - `DECISION`: whether the rule allows or denies the resource. - `STATUS`: whether the rule is in effect. A rule may be `inactive` if it's - overridden or suppressed (for example, when organization governance is - active, local rules are not evaluated and show as `inactive`). + overridden or suppressed — for example, when organization governance is + active, local rules are not evaluated. Inactive rules are hidden by default; + pass `--include-inactive` to list them. See + [Showing inactive rules](#showing-inactive-rules). - `RESOURCES`: the hosts or patterns the rule applies to. When organization governance is active, the output starts with a governance @@ -44,6 +46,29 @@ header showing which organization manages the policy and when it last synced: $ sbx policy ls Governance: managed by my-org [OK] last synced 13:54:21 +NAME TYPE ORIGIN DECISION STATUS RESOURCES +allow AI services network remote allow active api.anthropic.com + api.openai.com +allow Docker services network remote allow active *.docker.com + *.docker.io +``` + +The governance header shows which organization is managing the policy and +confirms the daemon has successfully pulled the latest rules. If the sync +status shows an error or a stale timestamp, the daemon may not have the most +recent org policy. Run `sbx policy reset` to force a fresh pull. + +### Showing inactive rules + +When organization governance is active, local and kit-defined rules are not +evaluated, so `sbx policy ls` hides them by default. To list them too — for +example, to confirm which local rules the organization policy overrides — pass +`--include-inactive`: + +```console +$ sbx policy ls --include-inactive +Governance: managed by my-org +[OK] last synced 13:54:21 NAME TYPE ORIGIN DECISION STATUS RESOURCES balanced-dev network local allow inactive api.anthropic.com allow AI services network remote allow active api.anthropic.com @@ -52,10 +77,8 @@ allow Docker services network remote allow active *.doc *.docker.io ``` -The governance header shows which organization is managing the policy and -confirms the daemon has successfully pulled the latest rules. If the sync -status shows an error or a stale timestamp, the daemon may not have the most -recent org policy. Run `sbx policy reset` to force a fresh pull. +Inactive rules show with an `inactive` status. They have no effect while +organization governance is active. Use `--type network` to show only network rules. Without a sandbox argument, `sbx policy ls` shows every rule across all sandboxes. Pass a sandbox name to diff --git a/content/manuals/ai/sandboxes/governance/org.md b/content/manuals/ai/sandboxes/governance/org.md index 902f6895dc..46e734a056 100644 --- a/content/manuals/ai/sandboxes/governance/org.md +++ b/content/manuals/ai/sandboxes/governance/org.md @@ -57,9 +57,10 @@ For the full syntax reference (exact hostnames, wildcard subdomains, port suffixes, and CIDR ranges), see [Policy concepts](concepts.md#network-rules). When organization governance is active, local network rules are not evaluated. -The organization policy is the only policy in effect. Local rules still appear -in `sbx policy ls` but with an `inactive` status. See [Monitoring](monitoring.md) -for how to read the rule view. +The organization policy is the only policy in effect. `sbx policy ls` hides +these inactive local rules by default. See +[Monitoring](monitoring.md#showing-inactive-rules) for how to list them and read +the rule view. ## Filesystem policies