> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mibyanai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Managed Scope

> Administrator-pinned, user-immutable config and secrets via a system-level managed directory

**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.

<Note>
  **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.
</Note>

## Where it lives

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

```text theme={null}
/etc/mibyan/
├── config.yaml     # managed config layer (wins over ~/.mibyan/config.yaml)
└── .env            # managed env layer (wins over ~/.mibyan/.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.

### 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.

```bash theme={null}
# Point managed scope at a custom directory (set by IT / the deployment, not the user)
export mibyan_MANAGED_DIR=/opt/org/mibyan-policy
```

<Warning>
  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.
</Warning>

## Precedence

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

| Tier | config.yaml | .env |
| - | - | - |
| 1 | `/etc/mibyan/config.yaml` (managed) | `/etc/mibyan/.env` (managed) |
| 2 | `~/.mibyan/config.yaml` (user) | `~/.mibyan/.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:

```yaml theme={null}
model:
  default: org/standard-model
```

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

<Note>
  **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.
</Note>

## Seeing what's managed

```bash theme={null}
mibyan config        # shows a header naming the managed source + the pinned keys
mibyan doctor        # reports the resolved managed dir + pinned key counts
```

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

```bash theme={null}
$ mibyan config set model.default my/model
Cannot set 'model.default': it is managed by your administrator
(/etc/mibyan/config.yaml) and cannot be changed.
```

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)

```bash theme={null}
sudo mkdir -p /etc/mibyan

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

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

sudo chmod 0755 /etc/mibyan
sudo chmod 0644 /etc/mibyan/config.yaml /etc/mibyan/.env
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.