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

# Hierarchical Settings & Org Control

> How org, project, folder, and user settings combine to control models, tools, safety policies, and telemetry for Droid.

Factory’s enterprise story is built on a **single, predictable settings hierarchy**. Instead of ad‑hoc per‑machine configuration, orgs express policy once and have it apply consistently across laptops, CI, VMs, and airgapped environments.

This page explains how the hierarchy works and how to use it to govern models, tools, safety policies, and telemetry.

***

## The four levels

Settings are defined in `.factory/` folders with a consistent structure at four levels:

```text theme={null}
Org         → Central `.factory/` bundle (or config endpoint)
Folder      → <git-root>/.../subfolder/.factory/
Project     → <git-root>/.factory/
User        → ~/.factory/
```

Each `.factory/` folder can contain:

* `settings.json` – general settings (models, safety, preferences, telemetry).
* `mcp.json` – MCP server configurations.
* `droids/` – droid definitions.
* `commands/` – custom commands.
* `hooks/` – hook definitions.
* `skills/` – skill definitions.

The **same schema** applies at every level. What changes is **precedence**.

***

## Settings JSON schema

Below is the full schema for org-managed settings. These are configured by org admins through the [Enterprise Controls](https://app.factory.ai) page in the Factory app. Every property is optional — omit any field you do not need to set.

<ResponseField name="sessionDefaultSettings" type="object">
  Session default preferences.

  <Expandable title="properties">
    <ResponseField name="model" type="string">
      Default model identifier (e.g. `claude-opus-4-6`, `gpt-5.3-codex`).
    </ResponseField>

    <ResponseField name="reasoningEffort" type="string">
      How much thinking the model does before responding. One of `none`, `dynamic`, `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`.
    </ResponseField>

    <ResponseField name="interactionMode" type="string">
      Droid interaction mode. One of `auto`, `spec`, `agi`.
    </ResponseField>

    <ResponseField name="autonomyMode" type="string">
      Autonomy mode for the session. One of `normal`, `spec`, `auto-low`, `auto-medium`, `auto-high`.
    </ResponseField>

    <ResponseField name="specModeModel" type="string">
      Model to use when spec mode is active.
    </ResponseField>

    <ResponseField name="specModeReasoningEffort" type="string">
      Reasoning effort override for spec mode. Same values as `reasoningEffort`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="maxAutonomyLevel" type="string">
  Maximum autonomy level any user or project can set. One of `off`, `low`, `medium`, `high`.
</ResponseField>

<ResponseField name="cloudSessionSync" type="boolean">
  Whether sessions are synced to the cloud.
</ResponseField>

<ResponseField name="includeCoAuthoredByDroid" type="boolean">
  Include a `Co-authored-by: Droid` trailer in git commits.
</ResponseField>

<ResponseField name="enableDroidShield" type="boolean">
  Enable Droid Shield safety checks.
</ResponseField>

<ResponseField name="ideAutoConnect" type="boolean">
  Automatically connect to the IDE on session start.
</ResponseField>

<ResponseField name="commandAllowlist" type="string[]">
  Shell command patterns that are always allowed (accumulated across levels).
</ResponseField>

<ResponseField name="commandDenylist" type="string[]">
  Shell command patterns that are always denied (accumulated across levels).
</ResponseField>

<ResponseField name="customModels" type="object[]">
  Org-provisioned custom model definitions.

  <Expandable title="properties">
    <ResponseField name="model" type="string" required>
      Model name sent to the provider API.
    </ResponseField>

    <ResponseField name="id" type="string" required>
      Unique identifier for this custom model entry. Must start with `custom:` (e.g. `custom:my-internal-model-v1`).
    </ResponseField>

    <ResponseField name="index" type="integer" required>
      Display order index.
    </ResponseField>

    <ResponseField name="baseUrl" type="string" required>
      Base URL of the model API endpoint.
    </ResponseField>

    <ResponseField name="apiKey" type="string" required>
      API key for authenticating with the provider.
    </ResponseField>

    <ResponseField name="provider" type="string" required>
      Provider type. One of `anthropic`, `openai`, `generic-chat-completion-api`, `factory`, `google`, `xai`, `voyage`.
    </ResponseField>

    <ResponseField name="displayName" type="string" required>
      Human-readable name shown in the model picker.
    </ResponseField>

    <ResponseField name="maxContextLimit" type="integer">
      Maximum context window size in tokens.
    </ResponseField>

    <ResponseField name="enableThinking" type="boolean">
      Enable extended thinking / chain-of-thought.
    </ResponseField>

    <ResponseField name="thinkingMaxTokens" type="integer">
      Maximum tokens for the thinking phase.
    </ResponseField>

    <ResponseField name="maxOutputTokens" type="integer">
      Maximum output tokens.
    </ResponseField>

    <ResponseField name="extraHeaders" type="object">
      Additional HTTP headers to send with each request. Map of header name to value.
    </ResponseField>

    <ResponseField name="extraArgs" type="object">
      Additional provider-specific arguments passed to the API.
    </ResponseField>

    <ResponseField name="noImageSupport" type="boolean" required>
      Set to `true` if the model does not support image inputs.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="modelPolicy" type="object">
  Org-level model access control.

  <Expandable title="properties">
    <ResponseField name="allowedModelIds" type="string[]">
      Model IDs that are explicitly allowed. See [supported model IDs](#supported-model-ids) below.
    </ResponseField>

    <ResponseField name="blockedModelIds" type="string[]">
      Model IDs that are explicitly blocked.
    </ResponseField>

    <ResponseField name="allowCustomModels" type="boolean">
      Whether users may add their own custom models.
    </ResponseField>

    <ResponseField name="allowedBaseUrls" type="string[]">
      Base URLs that custom models are allowed to connect to.
    </ResponseField>

    <ResponseField name="allowAllFactoryModels" type="boolean">
      Allow all Factory-hosted models regardless of the allow/block lists.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="userModelPolicies" type="object">
  Per-user model overrides. Map of user ID to policy object.

  <Expandable title="properties">
    <ResponseField name="allowedModelIds" type="string[]">
      Model IDs this user is allowed to use.
    </ResponseField>

    <ResponseField name="blockedModelIds" type="string[]">
      Model IDs this user is blocked from using.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="enabledPlugins" type="object">
  Map of plugin name in `plugin@marketplace` format to `true` (enabled) or `false` (disabled). Plugins set to `true` are automatically installed on CLI startup once their marketplace is available.
</ResponseField>

<ResponseField name="extraKnownMarketplaces" type="object">
  Additional plugin marketplaces. Map of marketplace name to a source object. Marketplaces listed here are automatically cloned and registered on CLI startup.

  <Expandable title="properties">
    <ResponseField name="source" type="object" required>
      Marketplace source — one of the following shapes, discriminated by the `source` field:

      <Expandable title="github">
        <ResponseField name="source" type="string" required>
          Must be `"github"`.
        </ResponseField>

        <ResponseField name="repo" type="string" required>
          GitHub repository in `owner/repo` format.
        </ResponseField>
      </Expandable>

      <Expandable title="url">
        <ResponseField name="source" type="string" required>
          Must be `"url"`.
        </ResponseField>

        <ResponseField name="url" type="string" required>
          URL of the marketplace manifest.
        </ResponseField>
      </Expandable>

      <Expandable title="local">
        <ResponseField name="source" type="string" required>
          Must be `"local"`.
        </ResponseField>

        <ResponseField name="path" type="string" required>
          Local filesystem path to the marketplace.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="strictKnownMarketplaces" type="object[]">
  Marketplace sources that are strictly enforced. Each entry is a source object directly (e.g. `{ "source": "github", "repo": "owner/repo" }`), not wrapped in a `source` key like `extraKnownMarketplaces` values.
</ResponseField>

### Supported model IDs

The following model identifiers can be used in `allowedModelIds` and `blockedModelIds`:

| Provider        | Model IDs                                                                                                                                                                |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Anthropic**   | `claude-sonnet-4-5-20250929`, `claude-sonnet-4-6`, `claude-opus-4-5-20251101`, `claude-opus-4-6`, `claude-opus-4-6-fast`, `claude-opus-4-7`, `claude-haiku-4-5-20251001` |
| **OpenAI**      | `gpt-5.1`, `gpt-5.1-codex`, `gpt-5.1-codex-max`, `gpt-5.2`, `gpt-5.2-codex`, `gpt-5.3-codex`                                                                             |
| **Google**      | `gemini-3-pro-preview`, `gemini-3-flash-preview`, `gemini-3.1-pro-preview`                                                                                               |
| **XAI**         | `grok-code-fast-1`                                                                                                                                                       |
| **Open source** | `glm-5`, `glm-5.1`, `kimi-k2.5`, `kimi-k2.6`, `minimax-m2.7`                                                                                                             |

***

## Extension‑only semantics

Factory uses **extension‑only** semantics instead of traditional “override” behavior.

* Higher levels (org, project) **cannot be overridden** by lower levels.
* Lower levels (folder, user) can only **add** to what higher levels define when those fields are unset.
* This ensures org policies remain intact even as projects and users customize their experience.

There are three merge modes depending on the data type.

### 1. Simple values – first wins

For simple scalar values (strings, numbers, booleans):

* The first level that sets a value “wins.”
* Lower levels cannot change or remove that value.

Examples:

* `sessionDefaultSettings.model`
* `sessionDefaultSettings.autonomyMode`
* `maxAutonomyLevel`

This guarantees that org decisions (such as which models or autonomy levels are allowed) remain authoritative.

### 2. Arrays – union, cannot remove

Array fields accumulate across levels:

* Org entries are always present and **cannot be removed**.
* Project and folder levels can add more entries.
* User level can add more entries but cannot remove or weaken higher‑level entries.

Examples:

* Command **allow lists** and **deny lists**.
* Lists of enabled hooks or features.

This pattern is ideal for policies like “these commands are always denied” or “these hooks are always enabled,” while still allowing teams to extend the list.

### 3. Objects – keys are locked per level

For object fields:

* Keys defined at a higher level are **locked**; their contents cannot be changed by lower levels.
* Lower levels can add new keys but not modify or delete existing ones.

Examples:

* `customModels` – org defines `claude-enterprise`; projects can add `payments-gpt`, users can add `personal-experimental`, but none can change or remove `claude-enterprise`.
* MCP server definitions – org defines which servers exist and how they connect; projects decide which to use.

This keeps critical configuration (like model endpoints and MCP servers) under centralized control.

***

## Org configuration

Large organizations typically manage an **org‑level `.factory` bundle** or config endpoint that:

* Specifies allowed models, gateways, and BYOK policies.
* Defines global command allow/deny lists.
* Sets defaults for autonomy, reasoning effort, and safety features like Droid Shield.
* Configures OTEL defaults (endpoints, sampling, and attributes).
* Publishes org‑standard droids, commands, and hooks.

This bundle is distributed to all environments where Droid runs—developer machines, CI, VMs, and airgapped clusters.

Org policy is the foundation; projects and users build on top of it.

***

## Project and folder configuration

Projects and folders use `.factory/` directories checked into version control to specialize org policy for particular codebases and teams.

Common responsibilities include:

* Adding project‑specific models and gateways within the allowed set.
* Defining project‑specific droids (for example, `/migrate-service`, `/refactor-module`).
* Configuring hooks that know about the project’s tests, linters, and deployment processes.
* Tightening safety controls for high‑risk repositories.

Folder‑level `.factory/` directories are useful in monorepos where different subsystems have different policies.

***

## User configuration

Developers can configure `~/.factory/` for **personal preferences only** where higher levels are silent.

Examples:

* Choosing a preferred model from the allowed set.
* Setting default behavior for display options and minor UX preferences.
* Enabling additional hooks or tools that do not conflict with org policy.

Because of extension‑only semantics, users cannot:

* Re‑enable models or tools that org or project settings have disallowed.
* Loosen command allow/deny lists.
* Reduce autonomy or safety requirements set by org or project.

***

## Example: enforcing a model policy

Suppose your org wants to:

* Allow only approved enterprise models.
* Disallow user‑supplied API keys.
* Force all prompts through a particular LLM gateway.

You would:

1. Define the allowed models and gateway endpoints in the org `.factory/settings.json`.
2. Set a policy flag to disable user BYOK entirely.
3. Configure hooks to verify that any model selection or endpoint use matches the org‑approved set.

Projects and users can still choose **which of the approved models** to use for different tasks, but cannot break these guarantees.

***

## Example: environment‑specific autonomy

Consider an org that wants to:

* Allow high autonomy in CI and sandboxed containers.
* Limit autonomy on developer laptops.

You could:

1. At org level, set `maxAutonomyLevel` to `high`.
2. In project settings, define environment‑aware hooks that:
   * Inspect environment tags (for example, `environment.type=local|ci|sandbox`).
   * Downgrade or block autonomy levels above `medium` when running on laptops.
3. Optionally, define stricter folder‑level policies for particularly sensitive repos.

Again, users cannot override these rules; they can only choose safer personal defaults within the allowed space.

***

## Example: full org-managed settings

```json theme={null}
{
  "sessionDefaultSettings": {
    "model": "claude-opus-4-6",
    "reasoningEffort": "high",
    "interactionMode": "auto",
    "autonomyMode": "auto-medium",
    "specModeModel": "claude-sonnet-4-6",
    "specModeReasoningEffort": "medium"
  },
  "maxAutonomyLevel": "high",
  "cloudSessionSync": true,
  "includeCoAuthoredByDroid": true,
  "enableDroidShield": true,
  "ideAutoConnect": true,
  "commandAllowlist": ["npm *", "yarn *", "pnpm *", "make *"],
  "commandDenylist": ["rm -rf /", "sudo *"],
  "customModels": [
    {
      "model": "my-internal-model",
      "id": "custom:my-internal-model-v1",
      "index": 0,
      "baseUrl": "https://llm-gateway.internal.example.com/v1",
      "apiKey": "${INTERNAL_MODEL_API_KEY}",
      "provider": "generic-chat-completion-api",
      "displayName": "Internal Model v1",
      "maxContextLimit": 128000,
      "enableThinking": true,
      "thinkingMaxTokens": 8192,
      "maxOutputTokens": 16384,
      "extraHeaders": {
        "X-Team": "platform"
      },
      "extraArgs": {},
      "noImageSupport": false
    }
  ],
  "modelPolicy": {
    "allowedModelIds": ["claude-opus-4-6", "claude-sonnet-4-6", "gpt-5.3-codex"],
    "blockedModelIds": [],
    "allowCustomModels": true,
    "allowedBaseUrls": ["https://llm-gateway.internal.example.com/v1"],
    "allowAllFactoryModels": false
  },
  "userModelPolicies": {
    "user-abc-123": {
      "allowedModelIds": ["claude-opus-4-6"],
      "blockedModelIds": []
    }
  },
  "enabledPlugins": {
    "my-org-plugin@internal-marketplace": true,
    "experimental-plugin@internal-marketplace": false
  },
  "extraKnownMarketplaces": {
    "internal-marketplace": {
      "source": {
        "source": "github",
        "repo": "my-org/factory-plugins"
      }
    }
  },
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "my-org/factory-plugins"
    }
  ]
}
```

***

## Feature‑specific enterprise controls

Beyond the general hierarchy, several features have dedicated org‑level toggles that override all lower levels:

* **Wiki Cloud Sync** (`wikiCloudSync`) – Controls whether wiki content can be generated and stored in Factory's cloud. When disabled, all wiki API endpoints are blocked and the CLI skips cloud upload and GitHub wiki sync. Enabled by default. See [Wiki](/cli/features/wiki/overview#wiki-cloud-sync).
* **Cloud Session Sync** (`cloudSessionSync`) – Controls whether session data is synced to Factory's cloud.

These controls are managed by org administrators in the **Enterprise Controls** section at [app.factory.ai](https://app.factory.ai).

***

## Putting it all together

The hierarchical settings system underpins everything described in the other enterprise pages:

* [Identity & Access Management](/enterprise/identity-and-access) – who can change which level of settings.
* [Privacy, Data Flows & Governance](/enterprise/privacy-and-data-flows) – where data and telemetry are allowed to go.
* [Network & Deployment Configuration](/enterprise/network-and-deployment) – which environments Droid can run in and how it connects.
* [LLM Safety & Agent Controls](/enterprise/llm-safety-and-agent-controls) – policies for commands, tools, and Droid Shield.
* [Models, LLM Gateways & Integrations](/enterprise/models-llm-gateways-and-integrations) – control over models, gateways, MCP servers, droids, and commands.
* [Compliance, Audit & Monitoring](/enterprise/compliance-audit-and-monitoring) – guarantees and telemetry used to prove compliance.

By expressing policy once at the right level, you can run Droid across cloud, hybrid, and airgapped environments **without per‑machine drift or one‑off configuration**.