Remote Dev Box (Secure VNC Environment)

A secure, Docker-based remote desktop environment featuring XFCE4, KasmVNC, and Traefik reverse proxy.

✨ Features

• XFCE4 Desktop: Full Linux desktop environment on Ubuntu 24.04.
• KasmVNC: High-performance, browser-native access (no client software needed).
• Traefik Proxy: Secure HTTPS routing with automated subdomain management.
• Tier 2 Proxy: remote-dev-box-proxy (rdb) for dynamic, container-internal routing of user apps.
  • Persistence: Routes are automatically saved to ~/.config/rdb/routes.json and survive container restarts.
• LLM Gateway: Integrated, centralized local LLM API proxy (llm.${DOMAIN_NAME}) routing to a dedicated llama.cpp inference engine.
• Portability-First: Environment-specific settings managed via .env (Domain, UID/GID, IP).
• Hashed Auth: Zero-trust credential management via htpasswd.
• Isolated Containers: Dedicated, private environments with standardized remote-dev-box- naming and matching internal hostnames.
• Customizable: Supports standard docker-compose.override.yml for overriding image versions, extra labels, or environment-specific configurations.
• Integrated Smoke Testing: New users are provisioned with admin/testing/ scripts for immediate end-to-end verification of their environment.
• Consolidated Template: A single, highly configurable dockerfile.baremetal template with toggleable "APP" sections for lean setups or full AI toolkits (Claude, Gemini, Cursor).
• Security Hardened:
  • Docker Socket Proxy: Traefik is isolated from the host's Docker daemon via a filtered proxy (remote-dev-box-proxy).
  • Version Pinning: All images are pinned to specific, verified tags for build stability and auditability.
  • Least Privilege: Passwordless sudo is disabled; root access requires explicit user authentication.
  • Resource Hardening: Configurable CPU, Memory, SHM, and PID limits enforced via .env to ensure host stability.
  • Network Tiering: Strict isolation between infrastructure (infra net), AI models (models net), and user containers (user net).
  • Capability Management: All infrastructure containers run with minimal privileges (ALL caps dropped by default).
  • Seccomp Sandboxing: Fine-grained system call filtering for both infrastructure and user containers.
  • Disk Quotas: Configurable hard limits per user (default 10GB) enforced via Sparse File Virtual Disks.
  • Reboot Resilience: Reboot-resistant "re-alignment" mechanism keeps virtual disks active.
  • Automated Verification: Integrated health checks and routing tests in deployment scripts.

Prerequisites

• Remote Host OS: Linux Ubuntu 24.04 (only supported OS)
• Docker & Docker Compose: Installed and running.
• Git & OpenSSL: Required for deployment and security.

🚀 Quick Start

1. Configure Environment

   cp .env.example .env
   # Edit .env to set your DOMAIN_NAME
   nano .env

2. Deploy: Initialize the deployment and roll out update infrastructure.

   # Generic command structure
   ./admin/deploy_update.sh --help

3. Create User: Provision new developer containers and virtual disks.

   # By default, uses dockerfile.baremetal
   ./admin/manage_users.sh add myuser mypassword

4. Configure DNS: See the setup guide for instructions. Option B is recommended.

5. Connect: Navigate to https://desktop.myuser.remote-dev-box/ and log in.

📚 Documentation

For detailed information, please refer to the following guides:

• Overview: Features, architecture, and core concepts.
• Setup & Deployment: Hardware requirements, installation, and DNS setup.
• User Management: Adding/removing users and admin script references.
• Development Workflow: Persistence strategy and container lifecycle.
• Internal Proxy: Guide to rdb CLI, dynamic routing, and persistence.
• Included Tools: Full list of AI CLI tools, editors, and utilities.
• Troubleshooting: Solutions to common connection and GUI issues.

🛠️ Security Note

This environment is designed for private network use. If hosting on a public IP, you MUST use a VPN/FIREWALL to access it. Never expose the backend ports directly to the internet.

---

Maintained by the Agentic Dev Team.