docs(enterprise): document system-managed settings file paths#1140
docs(enterprise): document system-managed settings file paths#1140factory-davidgu wants to merge 1 commit into
Conversation
Documents the hardcoded system-managed settings.json deployment paths (macOS /Library/Application Support/Factory/, Linux/WSL /etc/factory/, Windows C:\\Program Files\\Factory\\) so IT/MDM administrators can ship base org policy before any user authenticates. Source PR (factory-mono): Factory-AI/factory-mono#13857 Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
|
Droid finished @factory-davidgu's task —— View job Solid doc addition that explains system-managed settings paths and precedence, but a couple details need tightening: the failure-mode semantics (unreadable vs malformed) are easy to misinterpret, and the guidance should explicitly address file permissions/secret handling to avoid accidental key leakage. |
![factory-droid[bot]](https://avatars.githubusercontent.com/in/358017?s=60&v=4){kind=small}
|
|
||
| ## System-managed settings file | ||
|
|
||
| For deployments where org policy must be applied **before any user signs in** — managed laptops, CI runners that aren’t authenticated to Factory, airgapped or restricted‑network installs — IT/MDM administrators can drop a `settings.json` at a hardcoded, well‑known path on each machine: |
There was a problem hiding this comment.
[P1] [security] Warn about secrets and permissions for system-managed settings
This section recommends dropping a machine-wide settings.json while also stating it uses the full Settings schema (which includes secret-bearing fields like customModels[].apiKey and arbitrary headers); please add explicit guidance to (1) avoid placing long-lived secrets in this file when possible and (2) lock down filesystem permissions/ACLs so unprivileged local users cannot read it on shared systems, otherwise admins may inadvertently leak provider keys/tokens.
|
|
||
| The file uses the same [Settings JSON schema](#settings-json-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. |
There was a problem hiding this comment.
[P3] Define factoryTier and "developer-mode environment overrides"
The doc introduces factoryTier and "developer-mode environment overrides" as part of the resolution logic, but neither term is defined or linked anywhere else in the docs, which makes this guidance hard to operationalize; add a short definition (what factoryTier is used for and what overrides exist / how to enable them) or replace with user-facing terminology and a link to the relevant configuration surface.
|
|
||
| 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. |
There was a problem hiding this comment.
[P3] Clarify behavior for unreadable vs malformed system-managed settings
This paragraph says an absent or unreadable system-managed file falls back to the managed-settings endpoint, but a present-but-malformed file resolves to an empty policy and is "not silently bypassed"; if permission/IO errors are treated as "unreadable" and fall back without an explicit warning, admins may assume enforcement is active when it is not—please spell out which failure modes (missing vs permission denied vs parse/validation failure) map to fallback vs empty policy, and whether each path is logged/ surfaced.
1 participant
Description
Documents the hardcoded system-managed
settings.jsondeployment paths shipped in Factory-AI/factory-mono#13857 (CLI-656). IT/MDM administrators can drop a settings file at a well-known platform path so org policy is enforced before any user authenticates — useful for managed laptops, airgapped fleets, and CI runners./Library/Application Support/Factory/settings.json/etc/factory/settings.jsonC:\Program Files\Factory\settings.jsonChanges
docs/enterprise/hierarchical-settings-and-org-control.mdxcovering paths, precedence, tier behaviour, and failure semantics.docs/enterprise/network-and-deployment.mdxunder "Configuration surfaces".Japanese mirrors under
jp/enterprise/*are intentionally not updated in this PR — translation typically batches separately.