Repository navigation
Server Instances and Workspace Versions
One running SAP Bridge instance can serve multiple customer workspaces from one complete installation. Each workspace keeps its own database, encrypted vault, SAP connections, guards and project data. Use the shared-installation and symbolic-link setup for this common arrangement.
Use separate instances when you need independent sign-ins/settings or runtime-version comparisons. Each instance selects a complete runtime bundle, its own listening port and its own state directory; different runtime versions use separate complete bundles. Workspace data and native SAP resources have their own boundaries.
| Boundary | What it controls |
|---|---|
Complete sap-dev installation |
The executable, agent entry instructions, embedded guides, browser connector and bundled ABAP references used by that instance. |
| Listening port | The dashboard and /mcp endpoint reached by browsers and IDEs. The default is 58454. |
| Instance state directory | Remembered sign-in and runtime settings, GUI installation settings, caches and instance runtime state. The default is .instance-settings beneath the startup working directory. |
| Workspace | Its database, encrypted vault, guards, source/history and supported layout/schema formats. |
| SAP system and GUI | Their native authorizations, sessions, locks, debugger resources and GUI engine ownership remain shared external resources. |
Select a distinct absolute directory with --state-dir <absolute-directory>. Changing the port alone leaves the default state directory tied to the same startup working directory. Current startup reads the selected instance directory; it does not automatically import older per-user state from ~/.sap-bridge. Preserve those originals and configure the intended instance through its dashboard.
For example, run these Windows commands in separate terminals, using two complete installations:
& "C:\SAPBridge\stable\sap-dev\bin\sap-bridge.exe" --port 58454 --state-dir "C:\SAPBridge\stable-state"& "C:\SAPBridge\preview\sap-dev\bin\sap-bridge.exe" --port 58464 --state-dir "C:\SAPBridge\preview-state"On macOS or Linux, select the matching executable and use the same flags with absolute paths appropriate to that operating system. Older versions use their own supported startup contract.
Point each IDE's mcp-remote adapter to that instance's /mcp endpoint. The second example uses http://127.0.0.1:58464/mcp; the default setup uses http://127.0.0.1:58454/mcp. See Setup for the connection configuration.
Ask the agent to check sap_bridge_status and verify the returned runtime version and workspace dashboard URL. Open that URL, sign in to the intended instance and unlock the selected workspace. Each instance has its own selected sign-in, shared across its dashboards and local MCP chats. An organization selection is a feature context; it does not isolate local folders or SAP systems.
Agents read the connected runtime's current instructions with sap_read_docs and its released user guidance with collection: "wiki". Switch endpoints deliberately and refresh retained documentation after switching versions. Keep the executable, skill and matching reference set from the same update together.
The dashboard requests consent when the workspace layout or database schema actually needs an update. It shows the existing and requested format/schema transitions and offers Update workspace (irreversible) or Cancel. The update button becomes available after a ten-second review countdown; Cancel is available immediately and leaves the workspace unchanged.
A different Bridge build alone does not require migration consent or prevent otherwise format-compatible builds from opening the workspace. Accepting the dialog permits the pending migration; the resulting layout and database schema determine which runtimes can use the workspace. A runtime that cannot support the existing formats must be updated rather than bypassing the format checks. Database bootstrap reports that workspace preparation is required when an actual conversion is pending.
Use separate workspaces when comparing versions and keep a private backup before a real format/schema change if earlier-runtime rollback is needed. A separate instance directory does not copy the workspace, undo a conversion or supply its backup. See Upgrade#automatic-workspace-preparation for preservation and recovery.
Complete owned debugger, lock and GUI work through its original instance before replacing a runtime or browser connector. Instance-local storage does not make a shared SAP account, native GUI engine or target system independent. Existing permission guards, CTS checks and SAP authorization remain in force. See Debugging, SAP GUI lifecycle and Remote tunnels.