ArgoBox OS Architecture

ArgoBox OS is a browser-based WebOS that provides persistent desktop environments for multiple users with complete isolation, persistent storage, and service integration.

System Architecture

┌─────────────────────────────────────────────────────────┐
│ Browser Client (Astro + React)                          │
│ ├─ Home page with OS preview                            │
│ ├─ Desktop window manager (44+ apps)                    │
│ ├─ Admin panel (user/container management)              │
│ └─ Real-time notifications & messaging                  │
└──────────────────┬──────────────────────────────────────┘
                   │ HTTP/WebSocket
┌──────────────────▼──────────────────────────────────────┐
│ Cloudflare Pages / Workers                              │
│ ├─ Authentication & profiles                            │
│ ├─ Filesystem API (SMB mounting)                        │
│ ├─ Container lifecycle management                       │
│ ├─ Desktop state persistence (KV store)                 │
│ └─ Security & audit logging                             │
└──────────────────┬──────────────────────────────────────┘
                   │ SSH/Network
┌──────────────────▼──────────────────────────────────────┐
│ Backend Infrastructure                                  │
│ ├─ SMB storage (Unraid)                                 │
│ ├─ Per-user Docker containers                           │
│ ├─ Service containers (23 total)                        │
│ ├─ Cloudflare Tunnel (routing)                          │
│ ├─ Tailscale (VPN)                                      │
│ └─ Network isolation (firewall)                         │
└─────────────────────────────────────────────────────────┘

User Experience

Demo User (Ephemeral - 60 minutes)

Home Page — See OS preview embedded in landing page
Maximize — Click “Maximize” to open full desktop
Profile Selection — Choose profile (Homelab / Developer / Media / AI Operations)
Desktop — Use apps, terminal, file manager
Logout — Session data cleaned up automatically

Registered User (Persistent - 24/7)

Login — Authenticate via Cloudflare Access
Desktop Boot — Persistent container automatically started
Storage Mount — User’s home directory from Unraid SMB
Service Access — Personalized service access (bogie sees rTorrent, etc.)
State Persistence — Desktop windows, preferences saved to KV
Logout — State saved, container continues running

Admin User

Full Access — All desktop features + admin panel
User Management — Manage profiles, containers, permissions
Audit Logs — View all system events and access logs
Service Troubleshooting — Restart services, view diagnostics

5-Layer Security Model

Layer 1: Process Namespaces

Per-user UID/GID isolation (daniel=1000, bogie=1001, etc.)
Separate network/IPC/UTS/PID namespaces
Resource limits (CPU, memory, disk, processes)

Layer 2: Network Firewall

Per-user network isolation (172.17.X.0/24 subnets)
Deny-by-default egress (only whitelisted services)
DNS blocking for non-admin users
nftables/iptables enforcement

Layer 3: Capabilities & AppArmor

Linux capability dropping per profile
AppArmor profile enforcement
Seccomp syscall filtering
Read-only root filesystem for demo users

Layer 4: Service Access Control

Owner-based access (bogie owns bogie-rt)
Role-based whitelisting (admin/member/demo)
Service registry enforcement
Real-time access checks

Layer 5: Audit Logging

Event logging (container, service, network, privilege escalation)
30-day retention in Cloudflare KV
Real-time alerting
Compliance reports

User Profiles

User	Role	Profile	Container	Persistence	Access
daniel	admin	admin	argobox-daniel	24/7 persistent	Full
bogie	member	homelabber	argobox-bogie	24/7 persistent	LAN-only
mauve	member	homelabber	argobox-mauve	24/7 persistent	LAN-only
bea	member	developer	argobox-bea	24/7 persistent	LAN-only
demo	N/A	demo	ephemeral	60-min TTL	Whitelisted

Key Features

Persistent Storage

SMB mount from Unraid (192.168.20.50)
Per-user home directories with 100GB quotas
File upload/download via API
Terminal history persistence
Application preferences in home directory

Container Management

One persistent container per registered user
Ephemeral containers for demo users (60-min TTL)
Automatic startup on user login
Health monitoring
Graceful shutdown on logout

Service Integration

23 containers available on Unraid
Per-user access control (media, downloads, dev tools, etc.)
Real-time service health checks
Failure detection and recovery

Admin Panel

Container dashboard (list, filter, bulk operations)
User management (profiles, permissions, container control)
Desktop state viewer (windows, preferences, wallpaper)
Audit log viewer with filtering and reporting

Desktop State Persistence

Window positions and sizes
App preferences
Wallpaper and theme selection
Workspace layout
Taskbar state
Synchronized across sessions via KV store

Deployment Model

Hosting: Cloudflare Pages (global CDN) Compute: Cloudflare Workers (serverless) Storage: Cloudflare KV (state) + SMB (files) Infrastructure: Docker/Podman containers + Unraid + Tailscale

Performance Targets

Metric	Target
Desktop boot time	<5 seconds
File list (100 files)	<500ms
Container creation	<30 seconds
Terminal latency	<200ms
Health polling cycle	<3 seconds

Security Considerations

✅ Users cannot access other users’ containers or files
✅ Demo users isolated in ephemeral sandbox
✅ Non-admin users restricted to LAN access
✅ All actions logged and auditable
✅ Privilege escalation impossible (capabilities dropped)
✅ Network isolation via firewall + namespaces

Next Steps

Deployment: Follow the 6-week deployment roadmap
Administration: See Admin Panel Guide
Testing: See Testing Guide