🐸 Guac Bridge

SSH and OpenAI-compatible endpoints through Guacamole.

Expose a remote server’s SSH service or OpenAI-compatible API on your computer through its Guacamole web terminal. Use your usual SSH tools or LLM applications with the local port.

First-time setup

On Windows x86-64, run the installer from Releases. Select Add Guac Bridge to my user PATH if desired. On Linux x86-64, extract the native release archive.

Alternatively, install on either client with uv:

uv tool install guac-bridge
uv tool update-shell

No installation is needed on the server. The client uploads the matching bundled x86-64 helper through the Guacamole SSH terminal and reuses it on later connections. Linux servers need a shell and core utilities; Windows servers need PowerShell 5.1+ and a Windows SSH console. No runtime installation, administrator access or internet connection is required there. The user’s helper cache must allow execution.

Open the desired Guacamole terminal in your browser and copy its full URL. Use it as CONNECTION_URL below.

SSH bridge

Connect

guac-bridge ssh --url CONNECTION_URL

For a Windows server, add --server-os windows to either bridge command or the SSH Match hook. The default is Linux. RDP connections are not supported.

Enter your Guacamole username and password. In another terminal:

ssh -p 2222 SERVER_USERNAME@127.0.0.1

Keep the bridge running while connected. Stop it with Ctrl+C.

Use an SSH config

Add to ~/.ssh/config, replacing the URL and both usernames:

Host guac-server
    HostName 127.0.0.1
    Port 2222
    User SERVER_USERNAME

Match originalhost guac-server exec "guac-bridge ssh --ensure-running --save-password --url CONNECTION_URL --username GUACAMOLE_USERNAME --port %p"
Match all

Connect with ssh guac-server. The hook starts or reuses the background bridge and shows startup progress in your calling console. On first login it prompts in the calling console and saves your password to the system credential store after successful authentication.

The bridge stays running after SSH exits. Check or stop it with:

guac-bridge ssh --status --port 2222
guac-bridge ssh --stop --port 2222

Use a dedicated local port for each destination. Windows users can add --show-console to see the background bridge in a separate console.

LLM bridge

guac-bridge llm --url CONNECTION_URL

Enter your Guacamole credentials. The default local port is 8000, forwarding the server’s HTTP endpoint at 127.0.0.1:8000, including streamed responses. Use --target-port for a different server port and --port for a different local port.

Keep the bridge running while using the application. Stop it with Ctrl+C.

The commands guac-ssh-client and guac-llm-client also work. Run any client with --help for credential storage, certificates, background operation and transport tuning.

Transport defaults

The conservative configuration uses 4 TCP frame credits per connection, a 65536-byte frame limit, and 8 Guacamole input blobs awaiting gateway acknowledgements across the bridge. --window and --input-window are independent: increasing TCP credits no longer increases gateway buffering. See transport tuning for examples and the distinction between gateway and remote delivery acknowledgements. The independent --input-window option is available from v1.1.4.

Stop an existing managed bridge before changing transport settings. Its original settings remain in effect until it is restarted.

Contribution

The native CLI, helper and shared transport live in one Cargo package. The uv package installs the same native executables.

See Building, Testing, Transport debugging and Benchmarking. Submit issues and pull requests on GitHub.

Architecture

Each bridge opens a Guacamole WebSocket connection, checks or uploads its bundled helper, and runs it inside the remote terminal. Both bridge types forward TCP streams with bounded flow control; HTTP headers, bodies and streaming responses pass through unchanged. The helper exits with the session; only its cached executable remains.

See Connection details for diagrams, loopback interfaces and process lifetimes.