develop-synergy

Develop Synergy Safely

Protect the Active Runtime

Never stop, restart, signal, or reuse the SYNERGY_HOME of the Synergy instance carrying the current task. Do not run synergy stop, broad kill/pkill, or modify its data/lock files.

Read Development reference before choosing a mode.

Prepare an Isolated Home

1. Choose a dedicated parent directory and explicit free ports. Check listeners with lsof -nP -iTCP -sTCP:LISTEN or the platform equivalent; do not assume 4097 and 3001 are free.
2. Create the required .synergy parent and copy configuration:

DEV_HOME=/tmp/synergy-dev-<short-name>
mkdir -p "$DEV_HOME/.synergy"
cp -R ~/.synergy/config "$DEV_HOME/.synergy/config"

1. Copying configuration preserves provider settings but does not copy the separate credential store. Do not copy sessions, daemon state, locks, logs, cache, or Library data — the two model catalog files in step 4 are the sole cache exception. Seed only the fixture credentials a test requires inside the isolated home; never copy or overwrite the live credential store implicitly.
2. Copy model catalog data from the main home when the isolated environment cannot reach models.dev (offline or restricted-network debugging machines), so the isolated model list does not depend on a live models.dev fetch:

mkdir -p "$DEV_HOME/.synergy/cache"
for f in provider-model-catalogs.v1.json models.json; do cp ~/.synergy/cache/"$f" "$DEV_HOME/.synergy/cache/" 2>/dev/null || true; done

Treat these two cache files as seed data only: they are refreshed in place by the isolated runtime and never copied back to the main home. If the files are absent from the main home, the isolated instance will fetch models.dev on first use as usual.

1. Run bun dev prepare once when dependencies, generated SDK, Web dist, plugin SDK, or sandbox helper are missing.

Choose the Smallest Mode

SYNERGY_HOME="$DEV_HOME" bun dev server --port 4097
SYNERGY_HOME="$DEV_HOME" bun dev app --attach http://127.0.0.1:4097 --port 3001
SYNERGY_HOME="$DEV_HOME" bun dev web --server-port 4097 --app-port 3001
SYNERGY_HOME="$DEV_HOME" bun dev desktop --server-port 4097 --app-port 3001
SYNERGY_HOME="$DEV_HOME" bun dev desktop --managed --server-port 4097 --app-port 3001
SYNERGY_HOME="$DEV_HOME" bun dev send "test request"