Settings from the Syntic service

Your organization can keep its managed settings on the Syntic service instead of pushing files to every device. When a person signs in, the CLI fetches the policy that applies to their account, saves a copy, and treats it like any other managed policy. Nothing needs to be installed on the machine.

This page explains how the fetch works, when changes take effect, how it stacks with policy files, and how to make a machine refuse to start without it.

When to use it

	Service-delivered settings	Policy files and profiles on the device
Reaches	Every machine where a person signs in to your organization	Only the machines you manage
Needs device management	No	Yes
Applies before sign-in	No: the policy is fetched with the user’s credential	Yes
Can be changed by the user	No	No
Best for	Contractors, personal laptops, quick rollouts	Company-owned fleets with strict control

Many teams use both: device files for a fixed baseline (for example requireRemoteManagedSettings and minimumVersion), and the service for everything that changes more often.

Service-delivered settings are managed by your Syntic organization’s admins on the Syntic service. The keys are the same ones a policy file takes, listed on Managed settings.

How the fetch works

At start, after the API client is ready, the CLI asks the service for your organization’s managed settings, using the signed-in user’s credential.
It sends along the version tag of the copy it already has, so an unchanged policy costs only a short “nothing new” answer.
The answer is saved to ~/.syntic/remote-managed-settings.json (in SYNTIC_CONFIG_DIR if you moved the config folder). The file is written through a temporary file, so a crash never leaves half a policy behind.
Each start reads the policy from that saved copy.

The request has a 10-second limit. By default it runs in the background so it never slows the start.

The service answers	What the CLI does
Nothing changed	Keeps the saved copy and records the time of the check.
New settings	Replaces the saved copy.
This account has no managed settings	Saves an empty copy, so no service policy applies.
An error, or something that is not a settings object	Keeps the previous saved copy untouched. A broken answer never replaces a good policy.

The saved file looks like this:

{
  "fetchedAt": 1900000000,
  "etag": "\"v7\"",
  "settings": {
    "permissions": { "deny": ["WebFetch"] }
  }
}

Do not edit it by hand: the next fetch overwrites it.

When changes take effect

A background fetch that finds a changed policy saves it, and the change applies from the next start. A running session keeps the rules it started with.

To have a start wait for a fresh copy instead, set:

export SYNTIC_FORCE_REMOTE_SETTINGS_REFRESH=1

The start then waits up to 10 seconds for the answer. If the policy changed, the CLI prints:

Your organization's managed settings changed; they apply from the next start.

How it stacks with other policy

Managed sources are combined in this order, later ones winning on a conflicting value:

Policy files on the device (settings.policy.json and its drop-ins)
Settings delivered by the service
The macOS configuration profile

Lists such as permission rules are joined across all three. Together they form the managed layer, which sits above every user and project setting. Details are on Managed settings.

Require the settings at start

By default, a machine that has never fetched your policy (for example, it was offline at first sign-in) simply runs without it. To make it refuse to start instead, put this in a policy file or configuration profile on the device:

{ "requireRemoteManagedSettings": true }

With it set:

If there is no saved copy, the start waits up to 10 seconds to fetch one.
If the saved copy is more than 7 days old, the start also tries to refresh it first.
If neither works, the CLI exits with a message instead of starting.

Your organization requires its managed settings, and none could be loaded. Connect to the network and sign in, then start again.

Your organization's managed settings are 9 days old and could not be refreshed. Connect to the network and start again.

The key only counts in a local policy file or profile. It would make no sense coming from the service itself, since the service copy is what is missing.

⚠️

With requireRemoteManagedSettings on, people cannot work offline for more than a week at a time. Decide whether that fits your team before you turn it on.

When the fetch is skipped

Situation	Effect
`syntic --bare`	No fetch and no fail-closed check. Bare runs skip settings-driven extras.
Privacy level `disabled` (`SYNTIC_PRIVACY=disabled` or `SYNTIC_OFFLINE=1`)	No fetch. The saved copy still applies, and the fail-closed check still runs.
Not signed in	The request has no credential to use and fails; the saved copy, if any, still applies.

Check what is in force

Run syntic doctor. The Managed policy section lists the managed keys in force from every source, the service included. If a setting from the service does not show, check that the person is signed in to the right organization (syntic auth status) and try a start with SYNTIC_FORCE_REMOTE_SETTINGS_REFRESH=1.

Security notes

The fetch uses the same allowlisted Syntic API host as every other request; a project cannot point it elsewhere.
The saved copy lives in the user’s config folder. A user who edits it changes their own copy only until the next fetch. For rules that must hold even against the machine’s own user, use device policy files as well.
A project’s settings files can never add to or loosen the managed layer.

Managed settings Managed MCP servers