Managed Scope

Managed scope lets an administrator push a baseline of configuration and secrets that a standard (non-root) user cannot override. It is intended for fleet/org deployments where IT needs to pin, for example, the model provider, a shared API base URL, or security.redact_secrets: true across every user on a machine.

When a managed scope is present, the values it specifies win over the user's ~/.fabric/config.yaml, ~/.fabric/.env, and even the shell environment — for exactly the keys it pins. Everything else stays fully user-controlled.

Different from a package-manager–locked install

A package-manager–managed install (declarative-distro / formula) blocks all config mutation and tells you to use your package manager. Managed scope is a separate mechanism: it injects specific immutable values on a per-key basis rather than locking the whole config. The two are independent and can coexist.

Where it lives

Managed scope is read from a system-level directory, default /etc/fabric:

/etc/fabric/
├── config.yaml     # managed config layer (wins over ~/.fabric/config.yaml)
└── .env            # managed env layer (wins over ~/.fabric/.env + shell)

The directory and files are owned by root (directory mode 0755, files 0644): readable by everyone, writable only by an administrator. That filesystem permission is the enforcement mechanism — a standard user can read the managed files but cannot edit them.

Either file is optional. A missing managed directory or missing file simply means "no managed scope," and configuration resolves exactly as it does without the feature.

Precedence

For the keys a managed layer specifies, the order is (highest wins):

Tier	config.yaml	.env
1	/etc/fabric/config.yaml (managed)	/etc/fabric/.env (managed)
2	~/.fabric/config.yaml (user)	~/.fabric/.env (user)
3	built-in defaults	pre-existing shell environment

Merging is leaf-level: pinning model.default does not freeze the rest of model.*. A managed config.yaml of:

model:
  default: org/standard-model

forces model.default for every user while leaving model.fallback (and every other key) under user control.

Precedence note

For the keys it pins, managed scope deliberately wins over the shell environment too — otherwise it would not be "managed." This is the one place that inverts the usual "an environment variable overrides config.yaml" rule, and it applies only to the specific keys the managed layer specifies.

Seeing what's managed

fabric config        # shows a header naming the managed source + the pinned keys
fabric doctor        # reports the resolved managed dir + pinned key counts

If you try to change a managed value, Fabric refuses and names the source:

$ fabric config set model.default my/model
Cannot set 'model.default': it is managed by your administrator
(/etc/fabric/config.yaml) and cannot be changed.

The same applies to managed secrets — fabric config set / setup will not write a user value for an env key pinned by the managed .env.

Setting up a managed scope (administrators)

sudo mkdir -p /etc/fabric

# Pin some config values for every user on this machine
sudo tee /etc/fabric/config.yaml >/dev/null <<'YAML'
model:
  provider: nous
security:
  redact_secrets: true
YAML

# Optionally pin a shared, non-sensitive env value
sudo tee /etc/fabric/.env >/dev/null <<'ENV'
OPENAI_API_BASE=https://inference.example.com/v1
ENV

sudo chmod 0755 /etc/fabric
sudo chmod 0644 /etc/fabric/config.yaml /etc/fabric/.env

Changes take effect on the next Fabric start (a malformed managed file is logged loudly and ignored — it never blocks startup, but the admin should check fabric doctor to confirm the policy is being applied).

Security model and limitations (v1)

• Enforcement is filesystem permissions only. If a user has write access to the managed directory (or runs Fabric as root), managed scope is advisory.
• The managed .env is world-readable (0644), so any local user can read secrets pushed through it. Use it for shared, non-sensitive values (an org API base URL, feature defaults) rather than high-sensitivity secrets.
• The agent's own tools are not hard-blocked from a managed env value. A managed environment variable is applied at startup, but nothing stops the agent from setting a different value inside its own subprocess shell. v1 is a management-convenience boundary against a normal user, not an un-escapable sandbox.

The following are intentionally out of scope for v1 and may come later:

• A hard boundary that the agent itself cannot escape.
• Native managed locations on macOS and Windows (v1 is Linux/POSIX-first).
• Drop-in fragment directories (managed.d/) for layered policy.
• Signed / integrity-checked managed files.
• Remote / device-management (MDM) delivery.
• Tighter (group-scoped) permissions for managed secrets.