plugins_sync.py is the client script that runs on every developer's machine (typically automatically at Servoy start via start-servoy.cmd / start-servoy.sh).

It synchronises managed plugins from the central Gold Share into the local Servoy installation:

• Missing plugins are copied from the share.
• Outdated plugins (hash mismatch) are replaced with the current version.
• Plugins removed from the manifest are moved to a quarantine folder (no hard delete).
• Private / unmanaged plugins (not in the manifest, never registered as managed) are never touched.

• Python 3.10 or newer
• No external packages required (standard library only)
• Gold Share must be accessible (e.g. K:\ mapped on Windows)
• Local config file must exist (see below)

The config file is created once per developer machine. It is never committed to Git — every developer has their own local paths.

The easiest way is the interactive wizard:

python plugins_sync.py --init-config

The wizard:

1. Asks for a profile name — used as the config file name under ~/.servoy-sync/<name>.json
2. Asks for a display name (shown in the profile picker)
3. Asks for servoy_home and checks that the path exists and looks like a Servoy installation
4. Asks for gold_root and checks that the share is accessible
5. Asks for servoy_version — suggests the automatically detected version
6. Asks for mode (default: quarantine) and optional private_plugins patterns
7. Shows a summary and asks for confirmation before writing

Multiple profiles (e.g. stable + nightly):

python plugins_sync.py --init-config --profile stable
python plugins_sync.py --init-config --profile nightly

Each profile is saved as %USERPROFILE%\.servoy-sync\<name>.json. When you run --launch (or start-servoy.cmd) and multiple profiles exist, an arrow-key picker is shown so you choose which Servoy to start.

Afterwards run a status check to verify the setup:

python plugins_sync.py --status

Use docs/example.servoy-plugin-sync.json as a template:

copy "%~dp0..\docs\example.servoy-plugin-sync.json" "%USERPROFILE%\.servoy-plugin-sync.json"

Or create the file from scratch:

notepad "%USERPROFILE%\.servoy-plugin-sync.json"

File contents (template):

{
  "gold_root":      "K:\\SERVOY_GOLD\\",
  "servoy_home":    "C:\\servoys\\2025.12.1.4123\\",
  "servoy_version": "2025.12.1.4123",
  "mode":           "quarantine"
}

Tip – finding servoy_home: Open Windows Explorer and navigate to your Servoy installation. The folder you want contains two sub-folders: developer and application_server. Enter the full path to that folder as servoy_home, using double backslashes and a trailing \\.

Developer 1 – default path:

{
  "display_name":   "Stable 2025.12",
  "gold_root":      "K:\\SERVOY_GOLD\\",
  "servoy_home":    "C:\\servoys\\2025.12.1.4123\\",
  "servoy_version": "2025.12.1.4123",
  "mode":           "quarantine",
  "private_plugins": []
}

Developer 2 – Servoy under Program Files:

{
  "display_name":   "Stable 2025.12",
  "gold_root":      "K:\\SERVOY_GOLD\\",
  "servoy_home":    "C:\\Program Files\\Servoy\\2025.12.1.4123\\",
  "servoy_version": "2025.12.1.4123",
  "mode":           "quarantine",
  "private_plugins": []
}

Developer 3 – multiple profiles (stable + nightly):

Profile ~/.servoy-sync/stable.json:

{
  "display_name":   "Stable 2025.12",
  "gold_root":      "K:\\SERVOY_GOLD\\",
  "servoy_home":    "C:\\servoys\\2025.12.1.4123\\",
  "servoy_version": "2025.12.1.4123",
  "mode":           "quarantine",
  "private_plugins": []
}

Profile ~/.servoy-sync/nightly.json:

{
  "display_name":   "Nightly 2026.03",
  "gold_root":      "K:\\SERVOY_GOLD\\",
  "servoy_home":    "C:\\servoys\\2026.03.0.5000\\",
  "servoy_version": "2026.03.0.5000",
  "mode":           "quarantine",
  "private_plugins": ["hvo-pdf.jar"]
}

Only servoy_version (and optionally servoy_home) needs to change:

{
  "gold_root":      "K:\\SERVOY_GOLD\\",
  "servoy_home":    "C:\\servoys\\2026.3.0.5000\\",
  "servoy_version": "2026.3.0.5000",
  "mode":           "quarantine"
}

python plugins_sync.py [--config <path>] [--profile <name>] [--dry-run] [--verbose]
                       [--status] [--launch] [--init-config]

python plugins_sync.py --init-config

The wizard asks for profile name and display name first, then servoy_home, gold_root, servoy_version, mode, and optional private_plugins patterns.

Example session:

============================================================
 Servoy Gold Plugin Sync – Config Setup Wizard
============================================================

------------------------------------------------------------
 Step 1/6 – Profile name
------------------------------------------------------------
  Profile name [default]: stable
  ✓  Will save to: C:\Users\max\.servoy-sync\stable.json

------------------------------------------------------------
 Step 2/6 – Display name
------------------------------------------------------------
  Display name [stable]: Stable 2025.12

------------------------------------------------------------
 Step 3/6 – Servoy installation folder (servoy_home)
------------------------------------------------------------
  servoy_home: C:\servoys\2025.12.1.4123
  ✓  Detected installed version: 2025.12.1.4123

------------------------------------------------------------
 Step 4/6 – Gold Share root folder (gold_root)
------------------------------------------------------------
  gold_root: K:\SERVOY_GOLD
  ✓  'plugins' sub-folder found on share.

------------------------------------------------------------
 Step 5/6 – Servoy version (servoy_version)
------------------------------------------------------------
  servoy_version [2025.12.1.4123]:
  ✓  manifest.json found on share – version matches the Gold Share.

------------------------------------------------------------
 Step 6/6 – Mode & private plugins
------------------------------------------------------------
  mode [quarantine]:
  private_plugins (comma-separated fnmatch patterns, blank = none):

------------------------------------------------------------
 Summary – config to be written:
------------------------------------------------------------
{
  "display_name": "Stable 2025.12",
  "gold_root": "K:\\SERVOY_GOLD",
  "servoy_home": "C:\\servoys\\2025.12.1.4123",
  "servoy_version": "2025.12.1.4123",
  "mode": "quarantine",
  "private_plugins": []
}
  Target: C:\Users\max\.servoy-sync\stable.json

  Write this config? [Y/n]: Y
  ✓  Config written to: C:\Users\max\.servoy-sync\stable.json
  Run 'python plugins_sync.py --status' to verify the setup.

To create additional profiles:

python plugins_sync.py --init-config --profile nightly

python plugins_sync.py

Expected output (example):

2026-03-02 08:00:01  INFO      Config:          C:\Users\max\.servoy-plugin-sync.json
2026-03-02 08:00:01  INFO      Gold manifest:   K:\SERVOY_GOLD\plugins\servoy-2025.12.1.4123\manifest.json
2026-03-02 08:00:01  INFO      Gold files dir:  K:\SERVOY_GOLD\plugins\servoy-2025.12.1.4123\files
2026-03-02 08:00:01  INFO      Local plugins:   C:\servoys\2025.12.1.4123\application_server\plugins
...
2026-03-02 08:00:01  INFO      === Phase 1: Install / Update managed plugins ===
2026-03-02 08:00:02  INFO        Installed: myplugin.jar
2026-03-02 08:00:02  INFO        Updated:   subfolder/another.jar
2026-03-02 08:00:02  INFO      === Phase 2: Quarantine removed managed plugins ===
2026-03-02 08:00:02  INFO        Nothing to quarantine.
2026-03-02 08:00:02  INFO      Result: SUCCESS (0 warnings)

python plugins_sync.py --dry-run --verbose

Useful to preview what would happen before running the real sync.

python plugins_sync.py --config "D:\team\my-sync-config.json"

python plugins_sync.py --status

Example output:

================================================================
 Servoy Gold Plugin Sync – Status Report
================================================================

  Config version (servoy_version): 2025.12.1.4123
  Installed version (detected):    2025.12.1.4123  [✓]
  Manifest version:                2025.12.1.4123  [✓]
  Manifest generated:              2026-03-02

  --------------------------------------------------------------
  PATH                                       STATUS
  --------------------------------------------------------------
  myplugin.jar                               OK
  subfolder/another.jar                      OUTDATED (size …)
  newplugin.jar                              MISSING  → will be installed on next sync

  Summary: 2 ISSUE(S) FOUND

The STATUS column shows:

The report also shows plugins that would be quarantined on the next sync and lists private plugins (never touched).

The script automatically detects the installed Servoy version and cross-checks three sources:

The script scans <servoy_home>/developer/features/ for a directory whose name starts with com.servoy.eclipse.feature_. The suffix of that folder name is the full version string (e.g. 2025.12.1.4123) — the same information shown in Eclipse under Help → About Servoy Developer.

Fallback: if that folder does not exist, application_server/lib/version.txt is read. That file contains only the build number (4123), not a full version string.

Note: The installation folder name (e.g. C:\Servoys\servoy_4123) may contain a version-like string, but the script ignores it. Only servoy_home in the config matters.

• Only warnings are logged — the sync does not abort.
• Plugins are installed from the manifest regardless.
• The developer sees the warning and can react:
  • Update the config version (after a local Servoy upgrade)
  • Ask the Gold Maintainer (if the manifest seems outdated)

After every successful run the script saves a list of currently managed plugins to:

<servoy_home>\application_server\plugins\.gold_sync_state.json

Example content:

{
  "updated_at": "2026-03-02T08:00:02",
  "managed_paths": [
    "myplugin.jar",
    "subfolder/another.jar"
  ]
}

On the next run the script compares:

• What was managed last time? → state file
• What is managed now? → current manifest

Files that were previously in the state but are no longer in the manifest → moved to quarantine.

Files that were never in the state (private plugins) → never touched.

Plugins removed from the manifest are moved to:

<servoy_home>\application_server\plugins__quarantine\YYYY-MM-DD\

Example: C:\servoys\2025.12.1.4123\application_server\plugins__quarantine\2026-03-02\myplugin.jar

The date folder makes it easy to roll back if the manifest was wrong. Use clean_quarantine.py to remove old quarantine folders after the retention period.

The script writes simultaneously to stdout and a rotating log file:

<servoy_home>\application_server\plugins\gold_plugins_sync.log

The log file is capped at 2 MB with up to 3 backups (*.log.1, *.log.2, *.log.3), keeping total disk usage under ~8 MB.

Share not accessible:

ERROR  Manifest not found: 'K:\SERVOY_GOLD\plugins\servoy-2025.12.1.4123\manifest.json'
       Is the Gold Share accessible? Check that the network drive is mapped.

→ Exit code 1. start-servoy.cmd starts Servoy anyway.

File locked (Servoy still open):

WARNING  Cannot install 'myplugin.jar': [WinError 32] The process cannot access the file ...
         Tip: Close Servoy and retry.

→ Exit code 2. Servoy starts anyway. The sync will be retried on the next launch.

1. Developer opens Servoy via start-servoy.cmd (not servoy.exe directly).
2. start-servoy.cmd automatically runs python plugins_sync.py.
3. Sync successful (exit 0) → Servoy starts normally.
4. Sync with warnings (exit 2) or fatal (exit 1) → brief message in CMD window, Servoy starts anyway.

The script never creates or modifies files that are not listed in the manifest (and in the state) as managed.