Platform
- Termix web app via HTTPS
- Termix server installation: Docker Compose
- Termix version: 2.7.1
- Termix image:
ghcr.io/lukegus/termix:latest
- Termix image digest:
sha256:931e4ce466f4d29b157eb8d6dcd4d36ee5114495c6edddbb19d4e360e2a60f8d
- guacd:
guacamole/guacd:1.6.0
- guacd image digest:
sha256:8974eaa9ba32f713daf311e7cc8cd7e4cdfba1edea39eed75524e78ef4b08f4f
- Docker Engine: 29.2.0
- Docker host/target: macOS 26.5.1 (Build 25F80), Apple Silicon arm64
- Browser tested through the self-hosted Termix website
Related issue
This appears to be a regression or continuation of #906. The release notes indicate that macOS Screen Sharing and guacd protocol negotiation problems were fixed, but the same failure still occurs with Termix 2.7.1.
Problem
VNC connections from Termix to Apple’s built-in Remote Management/Screen Sharing service never display the desktop. The UI remains at Connecting to VNC session... and eventually reports that it cannot connect.
SSH, SFTP, Docker management, and host metrics for the same Mac work correctly.
macOS configuration
Under System Settings → General → Sharing → Remote Management:
- Remote Management is enabled.
- “VNC viewers may control the screen with password” is enabled.
- Access is allowed for all users.
- A dedicated VNC-only password is configured.
- TCP port 5900 is listening.
- The password stored in Termix matches the dedicated VNC password.
- The Termix VNC username field is blank.
Network verification
The guacd container can reach the Mac through both its LAN address and Docker’s host gateway:
Connection to <MAC_LAN_IP> 5900 port [tcp/*] succeeded!
Connection to host.docker.internal 5900 port [tcp/*] succeeded!
Reading the RFB banner from inside the guacd container succeeds:
52 46 42 20 30 30 33 2e 38 38 39 0a
This is RFB 003.889.
After responding with RFB 3.8, macOS advertises these security types:
That corresponds to seven advertised types, including standard VNC authentication type 2. Therefore, this does not appear to be a routing, firewall, port, or missing VNC service problem.
Steps to reproduce
- Run Termix 2.7.1 with
guacamole/guacd:1.6.0 using Docker Compose.
- Enable Remote Management on a Mac running macOS Tahoe 26.5.1.
- Enable “VNC viewers may control the screen with password.”
- Add the Mac as a Termix host.
- Enable VNC on port 5900 and enter the dedicated VNC password.
- Open Termix in a browser.
- Click VNC.
- Wait for the connection.
Expected behavior
The Mac desktop should appear and accept keyboard and mouse input.
Actual behavior
Termix remains on “Connecting to VNC session...” and guacd retries before terminating the connection.
guacd debug log
Sensitive identifiers have been redacted:
INFO: Creating new client for protocol "vnc"
INFO: Connection ID is "<redacted>"
DEBUG: Processing instruction: size
DEBUG: Processing instruction: audio
DEBUG: Processing instruction: video
DEBUG: Processing instruction: image
DEBUG: Processing instruction: timezone
DEBUG: Processing instruction: name
INFO: Cursor rendering: remote
INFO: User "<redacted>" joined connection "<redacted>"
DEBUG: Client is using protocol version "VERSION_1_5_0"
DEBUG: Handler not found for ""
DEBUG: Handler not found for ""
INFO: Connect failed. Waiting 1000ms before retrying...
INFO: Connect failed. Waiting 1000ms before retrying...
DEBUG: Handler not found for ""
ERROR: Unable to connect to VNC server.
INFO: User "<redacted>" disconnected
INFO: Last user of connection "<redacted>" disconnected
INFO: Connection "<redacted>" removed.
The Termix backend records the Guacamole connection opening and closing normally:
INFO Guacamole connection opened
INFO Guacamole connection closed
Docker Compose configuration
Relevant sanitized configuration:
services:
termix:
image: ghcr.io/lukegus/termix:latest
environment:
PORT: "8080"
ENABLE_TELEMETRY: "false"
GUACD_HOST: "guacd"
GUACD_TUNNEL_HOST: "termix"
GUACD_RECORDING_PATH: "/termix-data/session_recordings/guacamole"
depends_on:
- guacd
guacd:
image: guacamole/guacd:1.6.0Additional desktop-app observation
The native macOS Termix 2.7.1 app has a separate failure when using remote sync. The desktop app appears to add its remote-login JWT as a token query parameter and then add the encrypted Guacamole connection token using the same parameter name. The server consequently rejects the WebSocket connection before contacting guacd:
Token validation failed
Unexpected non-whitespace character after JSON at position 27
TypeError: Cannot read properties of undefined (reading 'connection')
at ClientConnection.connect
The browser does not produce this token error. In the browser, the request reaches guacd and then fails during the macOS VNC connection described above. This may warrant a separate issue, but it is included here in case it helps reproduce the desktop behavior.
Troubleshooting already performed
- Verified the Termix and guacd containers are healthy.
- Verified TCP 5900 from inside guacd.
- Verified the
RFB 003.889 server banner.
- Verified standard VNC authentication type
2 is advertised.
- Verified the dedicated VNC password is enabled and matches Termix.
- Tested using the browser to bypass the native-app token issue.
- Restarted guacd.
- Tested with guacd debug logging.
- Confirmed other Termix features work against the same host.
Please let me know if a packet capture, complete sanitized debug log, or another guacd build would help.
Platform
ghcr.io/lukegus/termix:latestsha256:931e4ce466f4d29b157eb8d6dcd4d36ee5114495c6edddbb19d4e360e2a60f8dguacamole/guacd:1.6.0sha256:8974eaa9ba32f713daf311e7cc8cd7e4cdfba1edea39eed75524e78ef4b08f4fRelated issue
This appears to be a regression or continuation of #906. The release notes indicate that macOS Screen Sharing and guacd protocol negotiation problems were fixed, but the same failure still occurs with Termix 2.7.1.
Problem
VNC connections from Termix to Apple’s built-in Remote Management/Screen Sharing service never display the desktop. The UI remains at
Connecting to VNC session...and eventually reports that it cannot connect.SSH, SFTP, Docker management, and host metrics for the same Mac work correctly.
macOS configuration
Under System Settings → General → Sharing → Remote Management:
Network verification
The guacd container can reach the Mac through both its LAN address and Docker’s host gateway:
Reading the RFB banner from inside the guacd container succeeds:
This is
RFB 003.889.After responding with RFB 3.8, macOS advertises these security types:
That corresponds to seven advertised types, including standard VNC authentication type
2. Therefore, this does not appear to be a routing, firewall, port, or missing VNC service problem.Steps to reproduce
guacamole/guacd:1.6.0using Docker Compose.Expected behavior
The Mac desktop should appear and accept keyboard and mouse input.
Actual behavior
Termix remains on “Connecting to VNC session...” and guacd retries before terminating the connection.
guacd debug log
Sensitive identifiers have been redacted:
The Termix backend records the Guacamole connection opening and closing normally:
Docker Compose configuration
Relevant sanitized configuration:
Additional desktop-app observation
The native macOS Termix 2.7.1 app has a separate failure when using remote sync. The desktop app appears to add its remote-login JWT as a
tokenquery parameter and then add the encrypted Guacamole connection token using the same parameter name. The server consequently rejects the WebSocket connection before contacting guacd:The browser does not produce this token error. In the browser, the request reaches guacd and then fails during the macOS VNC connection described above. This may warrant a separate issue, but it is included here in case it helps reproduce the desktop behavior.
Troubleshooting already performed
RFB 003.889server banner.2is advertised.Please let me know if a packet capture, complete sanitized debug log, or another guacd build would help.