Plugin safety

A plugin is code you choose to run. Installing one is closer to installing a command-line tool than to changing a setting. This page explains what a plugin can do, how to look one over before you install it, the checks Syntic Code applies for you, and the controls you and your organization have.

What a plugin can do

Component	What it can do on your machine
Hooks	Run shell commands when events happen, such as before a tool runs or when a session starts.
MCP servers	Start a local program, or connect to a remote one, and offer new tools to the agent.
Language servers	Start a program that reads your source files.
Monitors	Start a background command that streams its output into your session.
Commands and skills	Add instructions the agent follows, including inline shell steps.
Agents	Add helper agents with their own prompts and tool lists.
`bin/`	Put the plugin’s own executables first on `PATH` for the processes above.

All of these run with your user account’s rights. A hook that runs rm can delete what you can delete.

⚠️

Install plugins only from sources you trust, and review them like any other code you run.

What a plugin cannot do:

Raise its own permissions. Tools offered by a plugin’s MCP servers go through the same permission rules and approval prompts as any other tool. Plugin hooks follow the same rules as your own hooks.
Change your settings beyond one key. A plugin may ship default settings, but only agent (which agent the main session starts as) is honoured. It cannot change permission rules, the model or anything else that way.
Reach outside its own folder by path. Component paths in the manifest that use .. or are absolute are ignored at load time and flagged by syntic plugin validate.
Read your sign-in. Language servers started by plugins never inherit the CLI’s own credentials from your environment.
Smuggle commands through option values. When a hook uses ${user_config.KEY}, the value is passed as a quoted environment variable, never pasted into the shell text.

Review a plugin before installing

Look at the source. The marketplace entry says where the plugin comes from. For a git source, open the repository and read it.
List what it brings. After installing, syntic plugin details <plugin> shows its skills, commands, agents, hooks, MCP servers and language servers. Press Enter on it in /plugin for the same view.
Read the hooks and servers first. These run without the agent asking. Check hooks/hooks.json, .mcp.json, .lsp.json and any monitors in the manifest.
Try it in isolation. Load it for one run with syntic --plugin-dir ./plugin instead of installing it.
Turn it off if unsure. syntic plugin disable <plugin@marketplace> keeps it installed but inactive.

Remove a plugin you no longer trust

syntic plugin uninstall suspicious@somewhere
syntic plugin marketplace remove somewhere

Uninstalling deletes the plugin’s files. Its data folder under ~/.syntic/plugins/data/ stays; delete it by hand if you want it gone. Options marked sensitive live in your system’s credential store under plugin-option:<id>:<key>.

Checks Syntic Code makes for you

At install

Organization policy first. A plugin your organization has disabled is refused before anything is downloaded. So is a plugin from a marketplace source the policy blocks.
Safe names. Plugin and marketplace names are limited to letters, digits, ., _ and -, so a hostile catalog cannot make the CLI write or delete outside ~/.syntic/plugins/.
Dependencies stay home. A plugin may pull in dependencies only from its own marketplace. A dependency on another marketplace is refused with a note; install it yourself if you trust it.
Archives are unpacked carefully. A .zip may be pinned with #sha256=<hex> and is checked against it. Entries with absolute paths, .. steps or links are refused, every entry’s checksum is verified, and size and entry count are capped (100 MB archive, 300 MB unpacked, 20,000 entries).
npm packages run no scripts. A plugin from npm is checked against the registry’s integrity hash and unpacked directly; no install scripts run.
Release tags are made safely. syntic plugin tag runs git so that the repository’s own config and hooks cannot run code.

At load

Every time a session starts, each enabled plugin passes through a trust check:

Result	What happens
Trusted	The plugin is on your trusted list. It loads quietly.
Not on the list (default)	It loads, and a trust warning is written to the log.
Blocked	Lockdown is on and the plugin is not trusted, or managed policy disables it. It does not load.

Plugins loaded with --plugin-dir, --plugin-url or from pre-seeded folders go through the same checks as installed ones. Blocked plugins are reported in the plugin_errors list of a stream-json run’s first record, so automation can see them.

Your own trusted list

~/.syntic/plugins/policy.json lets you name the plugins and marketplaces you trust:

{
  "trusted": ["formatter", "acme"],
  "lockdown": true
}

An entry matches a plugin’s name or its marketplace’s name. With "lockdown": true, only trusted plugins load; everything else is blocked. Without lockdown, untrusted plugins still load.

Two environment variables do the same for a single machine or CI job:

Variable	Effect
`SYNTIC_PLUGIN_LOCKDOWN=1`	Forces lockdown on.
`SYNTIC_TRUSTED_PLUGINS=a,b,c`	Adds names to the trusted list.

Run without plugins

Option	What it skips
`--bare`	Installed plugins, settings hooks, skill discovery and background work. Folders named with `--plugin-dir` still load.
`--safe-mode` (or `SYNTIC_SAFE_MODE=1`)	Everything `--bare` skips, plus all MCP servers and memory files. Use it to rule plugins out when something misbehaves.
`syntic plugin disable-all`	Turns every installed plugin off until you enable them again.

Controls for organizations

Administrators can, through managed settings:

force a plugin off with "enabledPlugins": { "name@marketplace": false };
allow or block marketplace sources with allowedMarketplaces, blockedMarketplaces and strictKnownMarketplaces;
show a note at every install with pluginTrustMessage.

Marketplaces that need a login token (headersHelper) or are produced by a command are honoured only from your own settings or managed policy, never from a repository’s project settings. The details are on Plugins for your organization and Managed settings.

Code intelligence Create a plugin