Architecture

Understanding Kloudlite's architecture: Control Node and Workmachines

Control Plane

Control Node

{subdomain}.khost.dev

VM 1
Workmachine
Workspaces

Dev Containers

Environments

Services & Apps

VM 2
Workmachine
Workspaces

Dev Containers

Environments

Services & Apps

VM 3
Workmachine
Workspaces

Dev Containers

Environments

Services & Apps

Orchestration Flow
Workmachine Network
Workmachine
Workspaces
Environments

Control Node

The Control Node is the heart of your installation, running at {subdomain}.khost.dev. It's a dedicated VM that orchestrates everything within your installation.

Core Responsibilities

Team Access Management

Handles team member authentication, OAuth integration (GitHub, Google, Microsoft), and role-based access control for your entire team

Workmachine Orchestration

Provisions, configures, and manages VM instances for team members. Handles scaling, health monitoring, and resource allocation

Centralized Management

All environments, workspaces, configurations, and team resources are managed centrally through the Control Node's web interface

Backups & Recovery

Automated backups of managed state including configurations, team settings, and metadata. Point-in-time recovery for control plane data (excludes environment and workspace states)

Workmachines (User VMs)

Workmachines are individual VM instances where users actually run their development work. Each workmachine is isolated and contains two main components:

Environments

Isolated spaces where your application services run - think of them as different stages like development, staging, or production.

What runs in Environments:

  • Services via Docker Compose: Databases (PostgreSQL, MongoDB, MySQL), caches (Redis), message queues, APIs
  • Configuration: Environment variables, config files, secrets
  • Network Isolation: Each environment has its own network namespace with service discovery

Workspaces

Isolated development containers on workmachines. Each workspace provides network isolation, manages package access, and controls environment connectivity while sharing host-level resources.

What's in a Workspace:

  • Multiple Access Methods: VS Code Web, SSH (for desktop IDEs like VS Code, Cursor, IntelliJ), web terminal, and AI assistants (Claude Code, etc.)
  • Network Isolation: Each workspace controls its own network namespace, providing isolation and security
  • Package Management: Packages installed and persisted at workmachine host level using Nix, made available in workspace PATH based on each workspace's configuration
  • Environment Connection: Network namespace switches to access environment services by name
  • Shared Home Directory: Home folder (~) shared across all workspaces on the workmachine, tool configurations persist
  • Workspace Code Storage: Each workspace's code stored in ~/workspaces/[workspace-name]

Workspace-Environment Connection

Workspaces can connect to environments to access services. For example, your workspace can connect to a "development" environment to access its PostgreSQL database at postgres:5432

Key Architectural Principles

Data Isolation & Security

Your data never leaves your installation. Each workmachine is isolated with its own network namespaces and security boundaries

Resource Efficiency

Environments can be deactivated when not in use. Workspaces can be suspended. Workmachines scale based on team needs

Team Collaboration

Team members share environments and can discover each other's resources within the installation scope

Regional Deployment

Deploy in your preferred cloud region (AWS, GCP, Azure) close to your team for low-latency access

Next Steps

Installation Guide

Learn how to create your installation and set up the Control Node

Getting Started

Create your first workmachine, environment, and workspace