Hierarchical Settings & Org Control

​

The four levels

Org         → Central `.factory/` bundle (or config endpoint)
Folder      → <git-root>/.../subfolder/.factory/
Project     → <git-root>/.factory/
User        → ~/.factory/

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

​

Settings JSON schema

​

Supported model IDs

​

Extension‑only semantics

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

​

1. Simple values – first wins

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

• sessionDefaultSettings.model
• sessionDefaultSettings.autonomyMode
• maxAutonomyLevel

​

2. Arrays – union, cannot remove

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

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

​

3. Objects – keys are locked per level

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

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

​

Org configuration

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

​

Project and folder configuration

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

​

User configuration

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

• 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

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

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.

​

Example: environment‑specific autonomy

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

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.

​

Example: full org-managed settings

{
  "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"
    }
  ]
}

​

Putting it all together

• Identity & Access Management – who can change which level of settings.
• Privacy, Data Flows & Governance – where data and telemetry are allowed to go.
• Network & Deployment Configuration – which environments Droid can run in and how it connects.
• LLM Safety & Agent Controls – policies for commands, tools, and Droid Shield.
• Models, LLM Gateways & Integrations – control over models, gateways, MCP servers, droids, and commands.
• Compliance, Audit & Monitoring – guarantees and telemetry used to prove compliance.