Enterprise Controls & Managed Settings

Factory's enterprise story is built on a single, predictable settings hierarchy. Orgs express hard policy controls and shared defaults in managed settings, then let projects and users customize only where the policy allows it.

Enterprise Controls govern models, tools, safety policies, network restrictions, retention, plugin marketplaces, service accounts, and feature defaults across laptops, CI, VMs, and airgapped environments.

This page is the org-admin reference for the settings hierarchy, the precedence rules that decide who wins, the merge semantics for each data type, and the authoritative org-managed settings schema. For personal preferences a user manages in the Factory App, see App settings. For the CLI settings.json reference, see Settings. For per-feature how-tos, see Custom Models (BYOK), MCP, Sandbox, Hooks, Plugins, and Autonomy Levels.

The settings levels

Settings are authored in .factory/ folders, using the same schema at every level. What changes between levels is precedence.

Each .factory/ folder can contain:

• settings.json: general settings (models, safety, preferences, telemetry).
• hooks.json: hook definitions.
• mcp.json: MCP server configurations.
• droids/, commands/, skills/: droid, command, and skill definitions.

At resolution time the four authored levels are placed into a longer build order that also includes a command-line overlay, remote dynamic config, and hardcoded defaults. The full order, highest priority first, is:

For hard controls, the highest level present wins, so Org is authoritative: lower levels can extend a policy where the schema allows accumulation, but they can never weaken or remove it. For session defaults, the order inverts and the most-local level wins. The next section explains why.

How precedence works: hard controls vs session defaults

This is the single most important distinction on this page. Managed settings resolve through two precedence systems at once, and they run in opposite directions. For the user-facing perspective on how personal preferences interact with these controls, see App settings.

Session defaults rank levels so that lower (more-local) wins: Runtime is most authoritative, then Folder, Project, and User, with Org, Dynamic, and BuiltIn acting as fallbacks. So a user who sets a preferred model overrides the org's default model, and a --settings runtime overlay overrides even the user. These choices are still capped by hard controls: the org modelPolicy allowlist decides which models exist at all, and maxAutonomyLevel caps the effective autonomyLevel no matter who set it.

In short: orgs decide the boundaries (hard controls, top-down), and users pick their preferred defaults inside those boundaries (session defaults, bottom-up).

Merge semantics

Within each precedence system, the actual merge depends on the data type. Factory uses three merge modes so hard policy controls stay intact while defaults can still adapt to local context.

For example, if the org defines claude-enterprise in customModels, projects can add payments-gpt and users can add personal-experimental, but neither can change or remove claude-enterprise.

The scalar keys inside sessionDefaultSettings are the exception to "first wins": the most-local level wins, not the first. See How precedence works.

System-managed settings file

For deployments where org policy must be applied before any user signs in, including managed laptops, CI runners that aren't authenticated to Factory, airgapped installs, or restricted-network installs, IT/MDM administrators can drop a settings.json at a hardcoded, well-known path on each machine:

The file uses the same org-managed settings schema as the rest of this page.

When this file is present it is the authoritative source for org-level settings on that machine. It short-circuits any API fetch or developer-mode environment overrides for org settings. The factoryTier signal is still queried from the Factory API on a best-effort basis (failures are non-fatal) so enterprise-gated behaviors keep working for managed deployments.

If the file is absent or unreadable, Droid falls back to the existing org-settings flow (Factory App / managed-settings endpoint). If the file is present but malformed or fails schema validation, org settings resolve to an empty policy and the failure is logged. A broken admin deployment is not silently bypassed.

This is the recommended way to ship base policy with an MDM image or installer; users cannot override or weaken it.

Org-managed settings schema

Below is the full schema for org-managed settings. These are configured by org admins through the Enterprise Controls in the Factory App. Every property is optional; omit any field you do not need to set.

Session defaults

Autonomy, safety, and commands

Models and BYOK

For BYOK and gateway setup, see Custom Models (BYOK).

MCP

MCP access is allowlist-only. For server configuration, see MCP.

Plugins and marketplaces

For setup and rollout, see Internal Plugin Marketplaces and Plugins.

Network, sync, and retention

Feature controls

Droid Computers

Missions

Org administration

Supported model IDs

The identifiers used in allowedModelIds, blockedModelIds, and requireExplicitOptInModelIds are the model IDs listed on Models, which is the single source of truth for available models across providers. Unrecognized IDs are silently dropped rather than failing validation, so policies stay valid across model updates.

Level responsibilities

The same schema applies at every level; the typical division of labor is:

• Org publishes the authoritative policy: allowed models and gateways, BYOK rules, global command allow/deny/block lists, org-standard droids, commands, hooks, and plugin marketplaces, plus retention, cloud sync, network policy, and feature gates. This bundle is distributed to every environment Droid runs in.
• Project and folder .factory/ directories (checked into version control) specialize org policy for a codebase: project-specific droids and gateways within the allowed set, hooks that know the repo's tests and deploys, and tighter controls for high-risk repositories. Folder-level directories handle monorepos where subsystems differ.
• User ~/.factory/ holds personal session defaults where the active policy allows it: a preferred model from the allowed set, preferred reasoning effort, interaction mode, and autonomy level. See App settings for the personal preferences surface.

Because hard controls remain authoritative, users cannot re-enable disallowed models or tools, loosen command lists, or raise autonomy above an enforced ceiling.

Example: enforcing a model policy

Suppose your org wants to allow only approved enterprise models, disallow user-supplied API keys, and force all prompts through a particular LLM gateway. You would:

1. 1
   Define the allowed models and gateway endpoints in modelPolicy and customModels.
2. 2
   Set modelPolicy.allowCustomModels to false to disable user BYOK entirely.
3. 3
   Use modelPolicy.allowedBaseUrls to require approved gateway endpoints for custom models.

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

Example: environment-specific autonomy

Consider an org that wants high autonomy in CI and sandboxed containers but limited autonomy on developer laptops. You could:

1. 1
   At org level, set maxAutonomyLevel to high.
2. 2
   In project settings, define environment-aware hooks that inspect environment tags (for example environment.type=local|ci|sandbox) and downgrade or block autonomy above medium on laptops.
3. 3
   Optionally, define stricter folder-level policies for particularly sensitive repos.

Users can only choose safer personal defaults within the allowed space.

Example: full org-managed settings

{
  "sessionDefaultSettings": {
    "model": "<model-id-from-/models>",
    "reasoningEffort": "high",
    "interactionMode": "auto",
    "autonomyLevel": "medium",
    "specModeModel": "<model-id-from-/models>",
    "specModeReasoningEffort": "medium",
    "runInWorktree": false
  },
  "maxAutonomyLevel": "high",
  "builtInToolAutonomyOverrides": {
    "WebSearch": "high",
    "FetchUrl": "medium"
  },
  "subagentAutonomyLevel": "medium",
  "cloudSessionSync": true,
  "voiceDictationEnabled": true,
  "includeCoAuthoredByDroid": true,
  "enableDroidShield": true,
  "ideAutoConnect": true,
  "commandAllowlist": ["npm *", "yarn *", "pnpm *", "make *"],
  "commandDenylist": ["rm -rf /", "sudo *"],
  "commandBlocklist": ["shutdown", "mkfs", "curl"],
  "allowManagedHooksOnly": true,
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Execute",
        "hooks": [
          {
            "type": "command",
            "command": "\"$FACTORY_PROJECT_DIR\"/.factory/hooks/audit-command.sh",
            "timeout": 30
          }
        ]
      }
    ]
  },
  "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": ["<model-id-from-/models>"],
    "blockedModelIds": [],
    "allowCustomModels": false,
    "allowedBaseUrls": ["https://llm-gateway.internal.example.com/v1"],
    "allowAllFactoryModels": false
  },
  "mcpPolicy": {
    "enabled": true,
    "allowlist": ["internal-docs", "ticketing"]
  },
  "networkPolicy": {
    "allowedIps": ["10.0.0.0/8", "192.0.2.0/24"]
  },
  "sandbox": {
    "enabled": true,
    "mode": "per-command",
    "filesystem": {
      "denyRead": ["~/.ssh", "~/.aws"],
      "denyWrite": ["/etc"]
    },
    "network": {
      "allowedDomains": ["api.github.com", "registry.npmjs.org"]
    }
  },
  "restrictApiKeyCreationToManagers": true,
  "sessionRetentionDays": 90,
  "advancedAnalyticsEnabled": true,
  "disableWeeklyUsageSummary": false,
  "userModelPolicies": {
    "user-abc-123": {
      "allowedModelIds": ["<model-id-from-/models>"],
      "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"
    }
  ]
}

Models, gateways, MCP, and tooling

The hierarchy governs which models and external systems Droid can reach. The org-level controls are the schema fields above; each area also has a dedicated page:

• Models and BYOK: modelPolicy (allowedModelIds, blockedModelIds, allowCustomModels, allowedBaseUrls) and customModels. See Models for IDs and Custom Models (BYOK) for gateway and provider setup, including cloud platforms (Bedrock, Vertex, Azure OpenAI) and self-hosted endpoints.
• MCP servers: mcpPolicy (allowlist-only), plus mcpAutonomyOverrides and mcpAutonomyUrlOverrides for per-server or per-URL autonomy. See MCP.
• Droids, commands, and hooks: published in the org .factory bundle; set allowManagedHooksOnly to true to ignore project- and user-defined hooks. See Hooks and Agent Safety & Controls.

Putting it all together

Enterprise Controls underpin everything described in the other enterprise pages:

• Identity & Access: who can change which level of settings.
• Data Flows & Privacy: where data and telemetry are allowed to go.
• Deployment Patterns: which environments Droid can run in and how it connects.
• Agent Safety & Controls: policies for commands, tools, and Droid Shield.
• Compliance & Audit: 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.