Skip to main content
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 ~/.mibyan/config.yaml, ~/.mibyan/.env, and even the shell environment — for exactly the keys it pins. Everything else stays fully user-controlled.
Different from a package-manager–locked installA 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/mibyan:
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.

​
Relocating the directory

The location can be relocated with the mibyan_MANAGED_DIR environment variable (for containers or non-/etc deployments). This is a deployment/bootstrap path knob — like mibyan_HOME — set by the same administrator who owns the managed files. It is never persisted to any .env by Mibyan.
A user who can set mibyan_MANAGED_DIR can repoint managed scope at a directory they control, defeating it. In a real deployment this variable should be fixed by the administrator (e.g. baked into the service unit / container image), not left user-settable. mibyan doctor reports the resolved managed directory so a redirect is visible.

​
Precedence

For the keys a managed layer specifies, the order is (highest wins): Merging is leaf-level: pinning model.default does not freeze the rest of model.*. A managed config.yaml of:
forces model.default for every user while leaving model.fallback (and every other key) under user control.
Precedence noteFor 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

If you try to change a managed value, Mibyan refuses and names the source:
The same applies to managed secrets — mibyan config set / setup will not write a user value for an env key pinned by the managed .env.

​
Setting up a managed scope (administrators)

Changes take effect on the next Mibyan start (a malformed managed file is logged loudly and ignored — it never blocks startup, but the admin should check mibyan 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 Mibyan 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.