Metadata-Version: 2.4
Name: guac-bridge
Version: 1.1.4
License-File: LICENSE
Summary: SSH and OpenAI-compatible endpoints through Guacamole, powered by Rust
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Issues, https://github.com/himbeles/guac-bridge/issues
Project-URL: Repository, https://github.com/himbeles/guac-bridge

# 🐸 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](https://github.com/himbeles/guac-bridge/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:

```shell
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

```shell
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:

```shell
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:

```sshconfig
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:

```shell
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

```shell
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](docs/benchmarking.md)
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](crates/guac-bridge). The uv package installs the same native executables.

See [Building](docs/building.md), [Testing](docs/testing.md), [Transport debugging](docs/transport-debugging.md) and [Benchmarking](docs/benchmarking.md). Submit issues and pull requests on [GitHub](https://github.com/himbeles/guac-bridge).

## 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](docs/connections.md) for diagrams, loopback interfaces and process lifetimes.

