Architecture

System overview#

Le Bureau is a three-tier architecture. Your browser talks to a frontend layer, which delegates to a backend API, which orchestrates virtual machines on bare-metal infrastructure.

The three layers#

Frontend#

The frontend serves the dashboard, documentation, and marketing pages. It also acts as a secure proxy -- forwarding authenticated requests to the API service so that internal endpoints are never exposed directly to the browser.

When you open Le Bureau in your browser, you are talking to this layer. It handles OAuth authentication, session management, and renders the UI. Any action that touches infrastructure -- creating a desktop, fetching metrics, uploading files -- gets forwarded to the API service.

API Service#

The API service is a standalone application that owns all business logic. It manages:

• Desktop lifecycle (create, start, stop, delete)
• Virtual machine orchestration (cloning, initialization, health checks)
• File operations via SFTP
• Mission Control tasks and activity streams
• Stripe billing and subscription management
• API key authentication for programmatic access

The API service is the only component that talks directly to the cloud infrastructure and the virtual machines, which limits the attack surface to a single trust boundary.

Infrastructure (Virtual Machines)#

Desktops run as full virtual machines on dedicated bare-metal servers. Each desktop is a clone of a pre-configured template -- a pre-built Ubuntu 22.04 + XFCE image with the AI agent framework pre-installed.

VMs are isolated from each other at the hypervisor level. Each one gets its own CPU, RAM, disk, and network interface.

Request flow#

Here is what happens when you create a new desktop:

1. Browser -- you click "New Desktop" and fill in the form.
2. Frontend -- validates your session, forwards the request to the API service.
3. API service -- checks your subscription tier, clones the pre-configured template, injects your configuration, and starts the VM.
4. Infrastructure -- creates the VM, boots it, and reports status back to the API.
5. API -- polls the VM until it transitions from "booting" to "running", then marks the desktop as ready.

The whole process takes 30 to 60 seconds.

Real-time connections#

Three features use persistent WebSocket connections instead of standard HTTP:

• VNC viewer -- streams the desktop's display to your browser in real-time via a VNC server's native WebSocket support.
• Terminal -- provides a full shell session via xterm.js over WebSocket.
• Chat panel -- connects to the AI agent running inside the VM for live conversation.

A WebSocket proxy sits between your browser and the VMs, authenticating each connection and routing traffic to the correct virtual machine.

VM provisioning#

When a new VM boots for the first time, an initialization process runs that:

• Sets up the user account
• Injects your AI provider configuration (API key, model selection)
• Configures the AI agent framework
• Starts background services (VNC server, terminal server, agent gateway)
• Optionally enables persistent memory with embeddings

Every desktop starts from the same base image but gets personalized configuration at boot time.

Key design decisions#

• BYOK (Bring Your Own Key) -- Le Bureau does not store your AI provider credentials on our servers beyond the initial injection. Your API key goes directly into the VM.
• Template cloning -- instead of installing software at boot, we clone a pre-built template. Provisioning is fast and reproducible.
• Isolated VMs -- each desktop is a full virtual machine, not a container. Isolation is stronger and the environment is more realistic for AI agents.
• Secure proxy -- the frontend proxies API calls, keeping internal service URLs and authentication tokens off the client.