Manage policies

Once you have more than one policy source and more than one workspace, policy management becomes its own thing. This page covers the day-to-day commands: adding and removing sources, scoping to specific workspaces, controlling sync behavior, and verifying signatures.

Adding a policy source

A policy source is an OCI reference. It can point to the public Jozu Hub, a private Hub, or any other OCI-compliant registry. Always include the registry hostname in the ref.

# Public Jozu Hub
agentguard policy add jozu.ml/jozu/agentguard-policies:vm-standard

# Private Hub
agentguard policy add hub.acme.com/sec-team/policies:v3

# Authenticated private registry
agentguard policy add hub.acme.com/sec-team/policies:v3 -u deploy-bot -p "$REGISTRY_TOKEN"

If you leave the hostname off, Agent Guard resolves the ref against the local registry. That is only what you want when testing locally; for anything published, prefix with jozu.ml/ or your private Hub's domain.

The registry host is saved to ~/.agentguard/config.json and reused on every subsequent sync. Authentication tokens are stored in the macOS Keychain.

When a source is added, Agent Guard pulls it immediately. From that point on, every agentguard run re-syncs all configured sources before starting the agent.

Global versus workspace scope

Policies have two possible scopes:

• Global: Apply to every agentguard run, regardless of which workspace the agent is working in. Best for company-wide baselines (security admin policies, supply chain rules) that should never be bypassed.
• Workspace: Apply only when the agent runs against a specific workspace. Best for project-specific rules (team conventions, language-specific restrictions, repo-level constraints).

Both scopes are additive. When the agent runs, Agent Guard loads every global policy plus every workspace policy matching the current workspace path.

Add to global scope (the default):

agentguard policy add jozu.ml/jozu/agentguard-policies:vm-standard

Add to a workspace:

agentguard policy add frontend-team/rules:v2 -w ~/projects/frontend

Use -w . to scope to the current working directory:

cd ~/projects/frontend
agentguard policy add frontend-team/rules:v2 -w .

Listing what is active

agentguard policy list

Shows every configured source across all scopes:

SCOPE                              REF                                          LAST SYNC
global                             jozu.ml/jozu/agentguard-policies:vm-standard 2026-05-15 09:30
workspace (~/.../frontend)         hub.acme.com/frontend-team/rules:v2          2026-05-15 09:35
workspace (~/.../api-server)       hub.acme.com/backend-team/rules:v1           2026-05-15 09:36

Filter to a specific workspace:

agentguard policy list -w ~/projects/frontend

This shows global policies plus the workspace policies that apply to that path.

Removing a source

# Remove from global scope
agentguard policy remove jozu.ml/jozu/agentguard-policies:vm-standard

# Remove from a specific workspace
agentguard policy remove frontend-team/rules:v2 -w ~/projects/frontend

# Remove everything from global scope
agentguard policy remove --all

# Remove everything from a workspace
agentguard policy remove --all -w ~/projects/frontend

Removing a source also deletes the policy files cached locally for that source. Re-adding the source pulls the policies again from the registry.

Auto-sync behavior

Every agentguard run syncs all configured policy sources before starting the agent. If the security admin pushed a new version of a tier, the next run pulls it. This means policy updates propagate to developer machines without manual intervention.

To skip sync on a specific run (for example when working offline):

agentguard run claude-code --no-sync --workspace ~/projects/myapp

To disable auto-sync globally via environment variable:

AGENTGUARD_NO_SYNC=1 agentguard run claude-code --workspace ~/projects/myapp

To force a sync without running an agent:

agentguard sync

Useful for verifying that a new policy version is reachable before the next agent run.

Signature verification with cosign

Policies published to Jozu Hub can be signed with cosign. Signature verification is opt-in: if you do not configure a public key, signatures are not checked.

Pass a public key at add time:

agentguard policy add jozu.ml/jozu/agentguard-policies:vm-standard --pub-key /etc/agentguard/cosign.pub

The verification result is cached. Subsequent syncs of the same source use the same key, and the result is logged.

For long-running configurations, add the public key to Agent Guard's trusted-keys store once and let every policy source use it:

agentguard trusted-keys add /etc/agentguard/cosign.pub
agentguard trusted-keys list
agentguard trusted-keys remove <key-id>

When trusted keys are configured, every policy source pulled from a remote registry is verified against the trusted set. A signature mismatch blocks the pull and the previously-cached version (if any) stays in place.

Local refs (policies you packed yourself with kit pack and have not pushed to a registry) bypass cosign because there is no registry to fetch signatures from. To allow local refs explicitly, load an ArtifactPolicy that matches on artifact.registry == "localhost".

Picking a Hub

The public Hub at jozu.ml hosts the four pre-built tiers and is enough for individual developers. For shared organizations, custom scans, or larger storage you need a private Hub. See Where Agent Guard fits in Jozu for the comparison, or the Jozu Hub overview for the full Hub feature set.

A private Hub is referenced by its domain in policy refs:

agentguard policy add hub.acme.com/jozu/agentguard-policies:vm-standard
agentguard policy add hub.acme.com/sec-team/internal-policies:v5

The rest of the management flow on this page works identically whether the Hub is jozu.ml or a private domain.