Guacamoly remote-desktop

A distributed team — members across the US, the Netherlands, and Nairobi — needed browser-only access to a shared, geo-stable, audio-capable Linux desktop, each user isolated, with no VMs, VPN clients, or local installs to distribute. The remote box also had to present a controllable, geo-targeted egress IP while staying reachable for admin and access.

My role here is best framed honestly as architect, operator, and orchestrator of an AI-agent-driven infrastructure build. Much of the execution was Claude Code / Codex agents working over SSH; I scoped the work and the constraints, directed the agents, and debugged, validated, and owned the system end to end. Directing AI coding agents to operate real infrastructure is itself the differentiating skill.

It is a genuinely shipped, in-use system with named real users and live audio-enabled sessions — not a prototype — and it carried real production incidents through to root-caused fixes.

The stack is a self-hosted, browser-based multi-user remote-desktop platform on AWS EC2: Apache Guacamole 1.4.0 (with guacd compiled from source) fronting XRDP and TigerVNC desktops, MariaDB JDBC authentication, and Tomcat behind an nginx reverse proxy with self-signed TLS. The core operational concept is a two-user-system — Guacamole web users in MySQL must match isolated Linux users in /etc/passwd — where isolation comes from distinct Linux users, a hard-won lesson.

It served five isolated, audio-enabled Linux sessions across three countries on a single box, with a virtual-webcam pipeline (OBS → nginx RTMP → ffmpeg → v4l2loopback) and PulseAudio-over-RDP audio compiled from source. The whole thing was maintained as a three-way Git "triangle" keeping a local checkout, GitHub, and the EC2 production checkout in lockstep.

The hardest piece was the network layer: running a desktop-oriented commercial VPN on a headless server fights the OS at the kernel and firewall level. The solution was a WireGuard fwmark split tunnel plus a background nftables watcher that injects ACCEPT rules into the VPN’s lazily-created drop-policy chain the instant it appears — arrived at after four documented failed routing approaches.

I conceived and ran an AMI-free EC2-to-EC2 migration using AI agents over SSH: a guard-railed task spec with hard read-only rules on the source box, phased checkpoints, and tar-over-SSH plus single-transaction mysqldump data extraction. The rebuild was user-validated end to end — eight service ports live, the database connection count matching the old box, and RDP-plus-audio confirmed — with UID-matched user recreation and from-source component rebuilds.

Operations were run with production discipline: fail2ban jails on SSH and a custom Guacamole filter, an HTTP→HTTPS migration that also fixed browser-clipboard access (the clipboard API needs a secure context), swap provisioning and disk-cleanup playbooks, and severity-gated change management. The documentation is written for agents to consume safely — a 21-entry issue encyclopedia and a 40-plus-entry edge-case catalogue across twelve categories.

The netfilter depth is the standout: iptables mangle with fwmark marking, nftables chain semantics, policy routing with custom tables, and a one-second-poll background watcher with a 300-second timeout — real Linux networking, debugged honestly through its failure modes.

Five isolated, audio-enabled sessions for real users across three countries on one box, a fully user-validated server migration, and a deep headless-VPN firewall conflict solved and documented — with the netfilter work being the part that is hard to fake.

Kept honestly in view: this is not enterprise scale, and I do not claim SLAs, uptime, or latency numbers — none are evidenced. The OpenClaw agent-gateway sub-part was evaluated and prototyped, then parked, not shipped. The defensible story is depth and ownership of an AI-agent-assisted infrastructure build, not hand-typing every command or running at scale.