PluginsModsMods for administrators

Mods for administrators

This page is for people who look after Syntic Code on other people’s machines. It explains what a mod can and cannot reach, how mods get onto a machine, and the one control you have to keep them off.

What a mod is, in security terms

A mod is a program the user installs in their own config folder and switches on themselves. Syntic Code starts it beside each interactive session and gives it a narrow channel:

A mod canA mod cannot
Draw a short footer item, a two-row band and a small side paneRun Syntic Code tools (shell, file edits, web, MCP)
Hear five session events: start, end, turn start, turn end, mode changeSend text to the model or read the conversation
Post short notes that only the user sees, if granted notesApprove permission prompts or change the permission mode
Read the session id, model, mode, turn count, busy flag and folder, if granted session.readChange settings, install plugins or enable other mods

Those limits apply to what a mod asks Syntic Code to do. The mod itself is still a normal program running with the user’s rights. It can read and write the user’s files and reach the network like any other program the user runs.

⚠️

Treat enabling a mod like running any downloaded program. The built-in limits stop a mod from using the agent; they do not sandbox the program.

How mods reach a machine

There is exactly one way: the user copies a mod folder into ~/.syntic/mods/<name>/ (or mods/ under an absolute SYNTIC_CONFIG_DIR) and runs syntic mod enable <name>.

Things that cannot install, enable or grant a mod:

  • A repository. Project folders are never searched for mods. A .syntic/mods/ folder in a cloned repository is ignored, and project settings have no mod keys.
  • Plugins and marketplaces. Mods are separate from plugins. Installing a plugin never adds a mod.
  • Hand-editing the state file. Enabled mods and grants are recorded in ~/.syntic/mods.json (written with owner-only permissions on Unix). Even if that file is edited, a mod only gets permissions that are both recorded there and asked for in its own mod.json.
  • Headless runs. syntic -p and other non-interactive runs never start mods.

Permission grants

A mod can ask for two permissions in its manifest: notes and session.read. When a user runs syntic mod enable, the command prints each permission with a plain explanation and grants exactly the ones the manifest asks for at that moment.

If a later version of the mod asks for more, the new permission is not granted automatically. syntic mod list flags it as now also asks for: …, and the user must run syntic mod enable again to grant it.

syntic mod disable <name> switches the mod off and removes its grants.

What a running mod is given

ItemDetail
Working folderThe mod’s own folder, never the project.
EnvironmentEmpty except PATH (cleaned), HOME, USER, LOGNAME, locale and temp variables, a few Windows system variables, and four SYNTIC_MOD_* variables. Tokens, keys and project variables are not passed.
PATHRelative entries, missing folders and anything inside the opened project are removed; standard system folders are added.
Program lookupA relative command must stay inside the mod folder (no .., no symlink out).
Data folder~/.syntic/mod-data/<name>/, created owner-only on Unix.
Process groupIts own, on Unix. When the session ends, the mod and anything it started are stopped after a half-second grace period.
OutputText is stripped of control and direction-override characters and cut to fixed sizes before display.

Keep mods off on a machine

Set SYNTIC_DISABLE_MODS in the environment Syntic Code runs in. Any value other than empty, 0, false, no or off turns it on:

export SYNTIC_DISABLE_MODS=1

With the switch on:

  • no mod starts in any session started from that environment;
  • syntic mod list still lists installed mods and adds a line saying no mod starts this time;
  • syntic mod enable still records the choice, and says the mod stays off until the variable is unset.

Put the variable wherever you manage the user’s environment, such as a shell profile for all users or your device management tool. It is read from the process environment when the session starts.

There is no managed settings key, allow-list or block-list for mods today. The environment variable is the only organization-wide control. For plugin controls, see Plugins for your organization.

Review a mod before people use it

If your team shares mods, review them like any internal tool:

  1. Read mod.json. Check command, events, ui and permissions. A mod that only draws a status item needs no permissions.
  2. Read the program. Look at what it does outside the protocol: network calls, files it reads or writes, child processes.
  3. Check where it writes. A well-behaved mod writes only to $SYNTIC_MOD_DATA.
  4. Pin a version. Share the reviewed folder (for example, from a tagged commit in an internal repository) so people copy the version you reviewed.

Next steps

Troubleshoot a modmod.json reference