Skip to content

Running SAP GUI for Java in VDI

Jump to bottom
stud0709 edited this page Sep 4, 2026 · 1 revision

Running SAP GUI for Java in VDI / Remote Desktops

This guide explains how to automate SAP GUI for Java running inside remote environments such as Citrix, Windows Virtual Desktop (AVD), or remote jump hosts on Windows and macOS.

By combining the sap-bridge Nostr Relay Tunnel with the embedded SAP GUI Bridge Agent, your local AI IDE agent can inspect screens, read tables, enter data, select tabs, and execute transactions on a remote SAP GUI session without requiring inbound VPNs, open firewall ports, or direct network access to the SAP application server.

1. Architecture Overview

In many enterprise landscapes, developers connect to SAP systems via a remote desktop session inside Citrix or Azure Virtual Desktop where only SAP GUI and a web browser are accessible.

graph TD
    subgraph LocalWorkstation["Local Workstation (Laptop / PC / Mac)"]
        IDE["AI IDE (Antigravity / Cursor / VS Code)"]
        Daemon["sap-bridge daemon (Port 58454)"]
        IDE <--> Daemon
    end

    subgraph RelayCloud["Nostr Relays (Public or Corporate)"]
        WSS["E2EE Nostr WebSocket Relay (Outbound Port 443)"]
    end

    subgraph RemoteSession["Remote Session (Citrix / Windows Virtual Desktop / macOS)"]
        WebManager["Bridge Manager Web UI (http://127.0.0.1:58457/)"]
        Agent["sap-agent-bridge.jar"]
        SAPGUI["SAP GUI for Java (platin.jar)"]
        WebManager <--> Agent
        Agent <-->|"Injected JVMTI / jcmd"| SAPGUI
    end

    Daemon <-->|"AES-256-GCM Encrypted"| WSS
    WSS <-->|"AES-256-GCM Encrypted"| Agent
Loading
  • Zero Inbound Ports: All connections between your local machine and the remote desktop are initiated outbound over standard WebSocket secure connections (wss:// port 443).
  • End-to-End Encryption (E2EE): Every payload, script, and response is encrypted with AES-256-GCM using a 256-bit Pre-Shared Key (PSK) generated exclusively for your active pairing session.

2. Deploying the Agent to Your Remote Desktop

To bridge SAP GUI inside your remote session, you need sap-agent-bridge.jar present on the remote machine.

Inside your remote desktop browser, open your active ADT Tunnel page (e.g. https://<sap-host>:<port>/sap/bc/zsapdevtunnel or via transaction SICF). The page provides dedicated helper buttons located directly beneath the Live Activity Log to retrieve the agent:

Option A: BASE64 -> Agent (Best for Locked-Down VDIs)

  • In strict enterprise Citrix environments, file downloads in browsers may be blocked by group policy.
  • Clicking BASE64 -> Agent copies a self-contained PowerShell script to your clipboard that reconstructs sap-agent-bridge.jar directly from in-memory Base64 without needing external download access: 
    $b64 = "..."
[IO.File]::WriteAllBytes("sap-agent-bridge.jar", [Convert]::FromBase64String($b64))
  • Paste this into PowerShell on Windows to write the JAR file directly to your current folder.

Option B: Download SAP GUI Agent (One-Click Download)

  • If browser downloads are allowed in your remote desktop, click Download SAP GUI Agent.
  • The page streams the JAR binary across the active tunnel and triggers a standard browser download prompt to save sap-agent-bridge.jar.

3. Starting the Agent

Step 1: Launch SAP GUI for Java

Open SAP GUI for Java inside your remote desktop and log into your target SAP system (e.g. A4H, client 001).

Step 2: Start the Bridge Agent (No Parameters Needed)

Open your terminal inside the remote desktop:

  • On Windows: Open PowerShell or Command Prompt in the folder containing sap-agent-bridge.jar.
  • On macOS: Open Terminal.

Execute the command:

java -jar sap-agent-bridge.jar

The agent automatically:

  1. Scans active processes to locate the running SAP GUI for Java instance.
  2. Injects sap-agent-bridge.jar into SAP GUI using jcmd / JVMTI.
  3. Initializes the internal Bridge Manager server at http://127.0.0.1:58457/.

Tip

Optional: Pre-Connecting via CLI
If you prefer headless or automated startup with tunnels already connected, you can pass one or more pairing tokens directly on the command line:
java -jar sap-agent-bridge.jar <pairing-token>
The Command to start agent button on the tunnel page copies this pre-filled command to your clipboard.

4. Managing Connections via the Bridge Manager (http://127.0.0.1:58457)

SAP GUI Bridge Manager

Once attached, open http://127.0.0.1:58457/ in your remote browser to manage your connections:

1. Connect Target Systems

  1. Copy the Tunnel Pairing Token (from your local sap-bridge Web UI Dashboard card or the remote ZCL_SAP_DEV_TUNNEL page).
  2. Under "Connect New System", paste the token into the input field and click "Connect".
  3. The bridge establishes the encrypted Nostr WebSocket tunnel to your local AI agent.
  4. If you work across multiple SAP systems (e.g. DEV and QAS), simply paste and connect additional tokens — all active connections run concurrently within the same agent instance!

2. Live Monitoring & Dynpro Sessions

  • Active Nostr Tunnels: Displays connection health, assigned Nostr topic, and connected relay count (e.g. 3/3 connected).
  • Active SAP GUI Dynpro Sessions: Displays live details of all open sessions (System ID, Client, active Program, Dynpro screen number, Window Title, and User).
  • Live Activity Log: Real-time auto-scrolling log of relay connections, heartbeats, inbound MCP automation requests (/eval, /status, /screenshot), and chunked response deliveries.

3. Graceful Shutdown

Click [Stop Agent] at the top right to disconnect all active Nostr tunnels and release port 58457. SAP GUI will continue running uninterrupted.

5. Troubleshooting

1. JDK Requirement (jcmd Tool)

Attaching the agent to a running SAP GUI process requires the Java jcmd diagnostic utility:

  • jcmd is included with all standard Java Development Kits (JDK 11, 17, 21), such as Eclipse Adoptium Temurin or OpenLogic JDK.
  • If your remote desktop only has a minimal Java Runtime Environment (JRE), jcmd may not be present. Install a full JDK or configure JAVA_HOME to point to a valid JDK installation.

2. Updating the Agent Bytecode

Under the Java Virtual Machine specification, classes that have already been loaded into memory cannot dynamically redefine their method signatures or add new fields while the process is running.

  • If you download a new version of sap-agent-bridge.jar, simply close the SAP GUI for Java application window, launch SAP GUI again, and re-attach the new JAR.

3. Corporate Proxies and WebSockets

The agent connects to Nostr relays over outbound wss:// (WebSocket Secure) on port 443. If your corporate proxy requires proxy authentication or blocks public relays (e.g. relay.damus.io), specify internal company relay endpoints in your sap-bridge Web UI system settings.

Clone this wiki locally