Managed settings

Managed settings (also called organization policy) are settings an administrator sets for every person on a machine. They sit above user and project settings, and a few keys only count when they come from here. Use them to enforce permission rules, approve MCP servers and plugins, pin models, and keep everyone on a supported version.

For the bigger picture of a team rollout, start with Admin setup.

Ways to deliver a policy

Policy file locations

Each folder may hold settings.policy.json and a settings.policy.d/ folder. Policy is read only from these admin locations. A settings.policy.json inside a project folder is ignored, so a cloned repository cannot pose as your policy.

Split a policy across teams

Drop-in files in settings.policy.d/ are applied on top of the base file in alphabetical order, so a later name wins on a conflicting value. Lists such as permission rules are joined rather than replaced. A simple naming scheme keeps the order obvious:

/etc/syntic/
├── settings.policy.json          # security team: the baseline
└── settings.policy.d/
    ├── 10-models.json            # platform team: model choices
    ├── 20-mcp.json               # tooling team: approved MCP servers
    └── 90-announcements.json     # internal comms: start-up messages

How the sources combine

Managed sources are stacked in this order, each one overriding the one before:

1. Policy files (base, then drop-ins; on macOS, /etc/syntic first, then /Library/Application Support/Syntic)
2. Settings delivered by the Syntic service
3. The macOS configuration profile

The combined policy then sits on top of everything a user controls. Overall, settings are read in this order, later winning: user file, project file, local file, SYNTIC_SETTING_* environment variables, managed policy. Command-line flags for a single run still apply, but they cannot loosen a managed permission rule, re-enable a mode you switched off, or start a version outside your range.

Switches that only tighten

A few switches can be turned on by any settings file, including a user’s own, and once one file turns them on nothing turns them off again:

Deny rules work the same way: a deny rule from any source is kept, and no allow rule overrides it.

A program that embeds Syntic Code

A program that runs the CLI for its own users can pass managed settings in the SYNTIC_SDK_MANAGED_SETTINGS environment variable, as a JSON object. What happens to them depends on your policy:

Check that a policy is in force

Run syntic doctor on the machine. The report ends with the managed keys it found:

Managed policy
  minimumVersion = 0.1.0
  blockedMarketplaces = 2 entries
  sandbox.bwrapPath = /opt/bwrap

Managed policy: none means no source reached the machine. The same report lists settings entries that had to be dropped (for example a value of the wrong type) and allow rules that can never take effect.

When a policy file is broken

A policy file, drop-in or configuration profile that exists but cannot be read stops Syntic Code before a session starts:

Your organization's managed settings could not be loaded, so Syntic will not start:
  /etc/syntic/settings.policy.d/20-mcp.json: expected `,` or `}` at line 4 column 3
Ask your administrator to fix the file.

This is on purpose. A typo should never quietly drop your rules. Validate files with a JSON checker before you push them.

An example policy

{
  "model": "Syntic Code",
  "availableModels": ["Syntic Code", "Syntic Code Fast"],
  "permissions": {
    "deny": ["Read(.env)", "Read(*.pem)", "WebFetch(domain:pastebin.com)"],
    "disableBypassPermissionsMode": "disable"
  },
  "allowedMcpServers": [{ "serverUrl": "https://mcp.example.com/*" }],
  "strictKnownMarketplaces": [{ "pathPattern": "^example-org/" }],
  "minimumVersion": "0.1.0",
  "companyAnnouncements": ["Remember: no customer data in prompts."]
}

Permissions

Rules and modes are explained in Permission rules and Permission modes.

Hooks

See Hooks.

MCP servers

mcpServers, allowedMcpServers and deniedMcpServers control which tool servers people can use. The allow list only counts in managed policy. Matching rules, examples and what users see are on Managed MCP servers.

MCP channels (servers that push messages into a session) have their own switches: "channelsEnabled": false in policy turns them off, and allowedChannelServers narrows which servers may push.

Plugins and marketplaces

Marketplace entries are sources (owner/repo, git or https URLs, paths) or { "hostPattern": "<regex>" } / { "pathPattern": "<regex>" }. The check runs before anything is fetched. More on Plugins for your organization.

Models and sign-in

Versions and updates

Unlike the update check, no environment variable skips this gate. When several sources set a bound, the last one in the stacking order wins.

Run everything through a launcher

{ "processWrapper": "/opt/corp/bin/launch --audit" }

processWrapper (a string, or a list such as ["/opt/corp/bin/launch", "--audit"]) makes every shell command, hook and MCP server that Syntic Code starts go through your launcher. Use it for auditing or to apply your own process controls. The launcher must be an absolute path. It is read from managed policy only; user and project settings cannot set or clear it.

Messages to users

Messages between sessions

Skills

Put skills every user should have in /etc/syntic/skills (Linux), /Library/Application Support/Syntic/skills (macOS) or %ProgramData%\Syntic\skills (Windows), or point SYNTIC_MANAGED_SKILLS_DIR at a folder. skillOverrides in policy can hide or limit any skill (off, user-invocable-only, name-only).

Memory

An organization SYNTIC.md in a policy folder (for example /etc/syntic/SYNTIC.md) is loaded into every session on the machine, before user and project memory. See Memory.

Keys that only count in managed policy

These keys are ignored, or cannot be loosened, when they appear in a user or project file:

Turn optional traffic off for everyone

Privacy levels are set with environment variables, not settings keys. To stop the optional background calls (update check, connection warm-up, usage refresh, marketplace refresh) on every machine, set SYNTIC_PRIVACY=essential in the environment you deploy. See Data usage and privacy.