---
title: Organization Agent settings
canonical: "https://agentbarn.dev/guides/observe-and-govern/organization-agent-settings"
pubDate: "2026-08-29T00:00:00.000Z"
updatedDate: "2026-09-02T11:46:37.000Z"
author: Agent Barn
description: "Manage Organization Agent Settings, model inheritance, allowed models, Agent overrides, Runtime model changes, permissions, and audit events."
tags: [Observe and govern, How-to, Organization owners and administrators, Organization Agent Settings, model defaults, model inheritance, allowed models, Agent override, running model, pending model]
categories: [Guides, Observe and govern]
---

-   Organization governance
-   Agent models
-   12 minutes

Organization Agent Settings controls the default Runtime model Agents inherit, the models the Organization may select explicitly, and the impact of a model-policy change.

## Organization-scoped Agent defaults

Runtime model is currently the first and only Organization Agent Setting. It supplies defaults used by Agents unless they have an explicit override.

**Key principle**

**Defaults are resolved, not copied.** Changing an Organization default changes what inheriting Agents resolve on their next start; it does not rewrite every Agent record.

Open the Organization-wide administrative surface at:

```
/dashboard/{org_id}/settings?tab=agents
```

It contains the default model and source, inheriting and override counts, allowed models, and an expandable Agent model map.

## Resolve defaults and Agent overrides

```
effective_default_model(organization)
  = organization-owned default
  or platform default

effective_model(agent)
  = Agent-specific override
  or effective_default_model(organization)
```

1.  An Organization either owns a default or follows the installation platform default.
2.  Each Agent either inherits the Organization’s effective default or uses a specific override.

There is at most one Agent Settings row per Organization, created lazily on the first write. No settings row and a row with `default_model = null` are equivalent: both follow the platform default. An Organization that never customizes this surface tracks the installation’s current default; the creation-time value is not a permanent snapshot.

## Choose a default source

| State | Stored `default_model` | Source | Behavior |
| --- | --- | --- | --- |
| Follow platform | `null` | `platform` | Resolve the current installation default |
| Organization-owned | Concrete model | `organization` | Resolve the model selected by the Organization |

Selecting a concrete model creates or updates the Organization-owned setting. Clearing it with `null` resumes following the platform default. Omitting `default_model` from an update leaves the existing choice unchanged.

The read model includes `default_model`, `effective_default_model`, `default_model_source`, `inheriting_agent_count`, `override_agent_count`, and `updated_at`. The counts cover non-deleted Agents; `updated_at` is present after a persisted settings change.

## Keep allowed models separate from the default

| Setting | Meaning |
| --- | --- |
| Allowed models | Models or patterns that may be selected explicitly |
| Effective default | One model inherited by Agents without an override |
| Agent override | One explicitly selected model for one Agent |

```
Allowed models
├── model-a
├── model-b
└── model-c

Organization default
└── model-b

Agent A → inherits model-b
Agent B → overrides with model-c
```

Adding a model to the allowlist does not make it the default, and changing the default does not remove other allowed models.

### Preserve explicit consumers

An Organization-owned default must be in `allowed_models`. Selecting a default outside the list is rejected, and removing the selected default is rejected until it is changed or cleared. Explicit Agent overrides must also remain allowed; removing a pinned model is refused and identifies affected Agents. No Agent is silently repinned by an allowlist edit.

1.  Change the Organization default to another allowed model, or clear it.
2.  Update or clear every Agent override using the model.
3.  Save the revised allowlist.

**Platform-default exemption**

An Organization that follows the platform default does not permanently require that model in its allowlist. The platform value can change during deployment and may be outside that list; inheriting Agents may still use it. Explicit overrides and Organization-owned defaults remain subject to the allowlist.

## Validate patterns with the model catalogue

The allowlist supports exact model identifiers and supported glob patterns. An Organization-owned default must be one concrete catalogue model, not a glob.

New entries are checked against the current OpenRouter catalogue when available. If the catalogue is temporarily unavailable, the failure is logged, existing settings remain intact, and validation may be skipped so administrators are not locked out. Models that later disappear from the catalogue can remain as orphaned entries until removed.

When choosing a default, Agent Barn confirms the model is allowlisted and concrete, checks the live catalogue when available, saves the setting, then reports the resolved value and impact counts. When changing the allowlist, it preserves the owned default and explicit overrides, validates new entries where possible, retains intentional orphans, and rejects changes that would strand an explicit consumer.

## Choose inheritance or a custom model

An Agent model control offers two explicit choices: **default** (_Use organization default_) or **custom** (_Choose a specific model_).

Using the default stores the inheritance sentinel rather than copying the current model. Choosing a specific model creates an explicit override. Two Agents showing the same model can therefore have different sources: an inheriting Agent moves when the default changes, while a custom Agent remains pinned.

Changing an individual override requires permission to update that Agent. Agent Owner or Editor access alone does not grant the Organization-wide authority to change defaults or the allowlist.

## Understand effective, running, and pending models

| Field | Meaning |
| --- | --- |
| `effective_model` | Model the Agent would use if started now |
| `running_model` | Model loaded by the current Runtime |
| `pending_model` | Model that differs from the running model and will apply on restart |

The Runtime reads its model at startup and does not continuously reload Organization settings. When a running inheriting Agent’s default changes, its effective model changes while its running model remains the previous value; `pending_model` shows what will apply after restart.

```
Agent A running model: model-a
Organization effective default: model-b
Agent A pending model: model-b
```

Agent A continues using `model-a` until restarted. A default change does not hot-reload an active Agent or restart any Agent automatically.

## Review policy blast radius

A default-change confirmation should show how many Agents follow the default, which model they will use after restart, and how many explicit overrides remain unaffected. The model map lists each accessible Agent’s name, displayed model, `default` or `custom` source, and a pending-switch note when restart would change the model.

Summary counts include all non-deleted Agents in the Organization, even when the caller cannot see every Agent by name. They describe policy blast radius and do not bypass Agent Access.

### Organization follows the platform

```
Organization default: null
Platform default: model-a
Agent A: inherits
Agent A effective model: model-a
```

After deployment changes the platform default to `model-b`, Agent A resolves `model-b` on its next start.

### Organization owns a default

```
Allowed models: model-a, model-b
Organization default: model-b
Agent A: inherits
Agent B: override model-a
```

Changing the Organization default affects Agent A, but not Agent B.

## Permissions and audit behavior

Reading and writing Agent Settings requires `organization.update`. Organization Owners and Admins can manage it; Members cannot.

```
Organization Permission → Organization default and allowlist
Agent Access Permission → Individual Agent override
```

Meaningful default changes emit `organization.agent_settings.changed`. Allowed-model changes emit `organization.model_allowlist.changed`. Both use the Domain Event and security-audit path; an unchanged save emits no extra event. They are not Communications journal entries.

## API reference

```
GET /api/v1/organizations/{organization_id}/agent-settings
PUT /api/v1/organizations/{organization_id}/agent-settings
```

```
{
  "default_model": null,
  "effective_default_model": "<platform-model>",
  "default_model_source": "platform",
  "inheriting_agent_count": 3,
  "override_agent_count": 1,
  "updated_at": null
}
```

Select an Organization-owned default:

```
{
  "default_model": "<allowed-model>"
}
```

Resume following the platform:

```
{
  "default_model": null
}
```

Allowed models use the Organization update route, not the Agent Settings request:

```
PATCH /api/v1/organizations/{organization_id}

{
  "allowed_models": [
    "<model-or-pattern>"
  ]
}
```

## Related guides

-   [Create an Organization](/guides/get-started/create-organization)
-   [Manage Organizations and members](/guides/observe-and-govern/organizations-and-members)
-   [Roles, Permissions, and Agent Access](/guides/observe-and-govern/roles-and-permissions)
-   [Configure an Agent](/guides/agents/configuration) and [manage the Agent lifecycle](/guides/agents/lifecycle)
-   [Work with Domain Events and Delivery](/guides/develop/domain-events)