Architecture
MolnOS is a self-contained cloud control plane that runs entirely within your infrastructure. The entire platform fits in approximately 430KB of code with no external runtime dependencies. This architectural simplicity means you can understand how it works, run it anywhere, and move it when needed.
Design Philosophy
Section titled “Design Philosophy”The architecture centers on three principles that work together to create a different kind of cloud platform.
Microscale by design. The entire platform is a small set of files, currently totaling around 430KB. There are no external dependencies to manage, no complex installation procedures, and no sprawling microservices architecture. This isn’t a simplified version of something larger—it’s designed from the ground up to be small.
Self-contained operation. By default, everything runs on a single host using embedded storage and a single Node.js process for the control plane—every service you choose to run (e.g. Functions, Sites…) spawns its own parallel process. For larger deployments, cluster mode allows distributing capabilities across multiple hosts while maintaining simplicity. There’s no requirement for distributed systems, external databases, or cloud provider services. This makes MolnOS straightforward to operate and debug.
Sovereignty as default. All data and operations remain within your infrastructure. The platform makes no telemetry calls, no automatic updates, and no external network requests. You control where it runs and what it does.
Technology Stack
Section titled “Technology Stack”MolnOS runs on Node.js 24+, supporting both ARM and x86 architectures. This means it works on Raspberry Pi devices, Apple Silicon Macs, traditional x86 servers, and everything in between.
- MolnOS Databases uses PikoDB, an embedded key-value database that requires no separate installation or management.
- MolnOS Object Storage works like S3 but uses the local filesystem directly.
- MolnOS Functions use a lightweight wrapper to allow powerful, direct invocations of user’s JavaScript code with zero cold starts.
- MolnOS Applications use MikroAuth under the hood to enable secure sign-in to applications running on MolnOS.
- MolnOS IAM makes it easy to create flexible roles and policies for users and service accounts.
- MolnOS Observability writes logs directly to local files with automatic retention management.
None of these components require external services or network connectivity.
The platform exposes standard HTTP/REST APIs for all services. After installation, it operates fully offline.
Deployment Architecture Examples
Section titled “Deployment Architecture Examples”Single-Host Deployment
Section titled “Single-Host Deployment”┌──────────────────────────────────────────────────┐│ User Infrastructure ││ ││ ┌────────────────────────────────────────────┐ ││ │ Host (VPS / VM / Bare Metal / Edge) │ ││ │ │ ││ │ ┌──────────────────────────────────────┐ │ ││ │ │ MolnOS (~430KB) │ │ ││ │ │ + Data Directory │ │ ││ │ └──────────────────────────────────────┘ │ ││ │ │ │ ││ │ │ HTTP/REST │ ││ │ ▼ │ ││ │ ┌──────────────────────────────────────┐ │ ││ │ │ Web Console (Optional) │ │ ││ │ │ Static site for management UI │ │ ││ │ └──────────────────────────────────────┘ │ ││ │ │ ││ └────────────────────────────────────────────┘ ││ │ ││ │ API Calls ││ ▼ ││ ┌────────────────────────────────────────────┐ ││ │ Applications / Functions / Services │ ││ └────────────────────────────────────────────┘ │└──────────────────────────────────────────────────┘Multi-Instance Deployment
Section titled “Multi-Instance Deployment”┌──────────────────────────────────────────────────┐│ Load Balancer / Reverse Proxy │└────────┬─────────────────────────────┬───────────┘ │ │ ┌────▼─────┐ ┌────▼─────┐ │ MolnOS 1 │ │ MolnOS 2 │ │ Instance │ │ Instance │ └──────────┘ └──────────┘
Note: Each instance is independent. Data is notsynchronized automatically between instances.Use for isolation, not high availability.Cluster Deployment (Core/Worker)
Section titled “Cluster Deployment (Core/Worker)”┌──────────────────────────────────────────────────┐│ Core Node (main.example.com) ││ ││ ┌─────────────────────────────────────────────┐ ││ │ MolnOS (core mode) │ ││ │ - Routes requests to workers │ ││ │ - Runs Identity, Management locally │ ││ │ - Health checks workers │ ││ └──────────────┬──────────────────────────────┘ │└─────────────────┼────────────────────────────────┘ │ HTTP + Cluster Secret ┌─────────┴─────────┐ │ │ ▼ ▼┌───────────────┐ ┌───────────────┐│ Worker Node 1 │ │ Worker Node 2 ││ (Functions) │ │ (Storage) ││ │ │ ││ ┌───────────┐ │ │ ┌───────────┐ ││ │ MolnOS │ │ │ │ MolnOS │ ││ │ (worker) │ │ │ │ (worker) │ ││ └───────────┘ │ │ └───────────┘ │└───────────────┘ └───────────────┘
Note: Core routes requests to workers based oncapability. Workers validate cluster secret.No distributed state between nodes.Edge Deployment
Section titled “Edge Deployment”┌─────────────────────────────────────────┐│ Edge Location (Factory, Store, etc.) ││ ││ ┌───────────────────────────────────┐ ││ │ Raspberry Pi / Edge Device │ ││ │ │ ││ │ ┌─────────────────────────────┐ │ ││ │ │ MolnOS │ │ ││ │ │ - Local compute │ │ ││ │ │ - Local storage │ │ ││ │ │ - Offline capable │ │ ││ │ └─────────────────────────────┘ │ ││ │ │ │ ││ │ ▼ │ ││ │ ┌─────────────────────────────┐ │ ││ │ │ IoT Devices / Sensors │ │ ││ │ └─────────────────────────────┘ │ ││ └───────────────────────────────────┘ ││ ││ Optional: Periodic sync to central │└─────────────────────────────────────────┘Security Architecture
Section titled “Security Architecture”The permission model uses a hierarchical pattern: service.resource.action:target. For example, databases.table.read grants read access to all tables, while storage.bucket.write:my-bucket restricts write access to a specific bucket. You can use wildcards at any level—databases.* for all database operations, or * for full administrator access.
Users operate within roles that define their permissions. Each user can only access resources their roles explicitly permit, with no cross-user data leakage. Functions have optional permission scoping, preventing privilege escalation. Services enforce these permissions at API boundaries, requiring explicit grants for any cross-service access.
Performance Characteristics
Section titled “Performance Characteristics”MolnOS runs on modest hardware. It’s hard to be except on minimum specifications, but MolnOS does run already on something as small as a Raspberry Pi Zero 2W. No network connectivity is required except during installation.
Scaling
Section titled “Scaling”The platform scales vertically by adding faster CPU for higher concurrency, RAM for larger cache size, and faster storage (e.g. NVMe, local disks) for objects and logs. A single node should be able to handle thousands of requests per second. Because of the nature of MolnOS and Node.js, rather opt for faster and fewer vCPUs, than to have lots of vCPUs.
For horizontal scaling, run multiple independent instances behind a load balancer—but understand that each instance maintains its own data with no automatic synchronization. Use such patterns for tenant isolation rather than high availability.
The high performance nature of MolnOS comes largely from avoiding network overhead and abstraction layers. PikoDB key-value operations go straight to file-based persistence. JavaScript function cold starts, practically speaking, don’t exist. Object storage uses direct filesystem I/O with no network hops.
Portability
Section titled “Portability”MolnOS runs on Linux and macOS, supporting both ARM and x86 architectures. This means it works on Raspberry Pi devices at the edge, VPS instances from providers like DigitalOcean or Hetzner, bare metal servers, virtual machines, containers, or your development laptop. It runs everywhere the operating system and architecture match.
Data portability is straightforward because the entire installation is just a small set of files and a data directory. Copy the data directory for a complete backup. Migrate by stopping the source instance, copying the MolnOS files and the data directory to the destination, starting the new instance, and updating DNS or networking as needed. There’s no export process, no database dump required, and no vendor-specific formats to deal with.
The platform uses standard HTTP REST APIs, JSON data formats, and S3-like storage conventions. Extracting your data programmatically requires only HTTP requests and filesystem access.
Operational Considerations
Section titled “Operational Considerations”MolnOS is designed for simplicity rather than high availability. For workloads that benefit from distributing capabilities across hosts, cluster mode allows a core node to route requests to worker nodes running specific capabilities (e.g., Functions on a dedicated compute host). This is useful for resource isolation and scaling individual capabilities, but doesn’t provide automatic failover. If you need HA for critical workloads, run multiple independent instances behind a load balancer with external monitoring and application-level data replication.
For disaster recovery, automate backups of the data directory and store them off-host. Version control your function code and export critical database tables. Recovery means installing MolnOS on a new host, restoring the data directory, verifying services, and updating routing or DNS. The process takes minutes rather than hours because there’s no complex state to reconstruct.
The platform includes centralized logging. External monitoring can use the health check endpoint for uptime tracking.
Design Trade-offs
Section titled “Design Trade-offs”MolnOS optimizes for:
- Focus over sprawling features,
- Portability over vendor integration, and
- Self-containment over distributed resilience.
This means the platform intentionally doesn’t provide built-in high availability, automatic multi-region replication, managed database backups, CDN functionality, relational database queries, or container orchestration. While cluster mode enables distributing capabilities across hosts, it doesn’t include automatic failover or state synchronization. These are deliberate omissions to keep the system microscale and understandable. When you need these capabilities, combine MolnOS with external tools or services rather than expecting them built-in.
The architecture proves that core cloud primitives don’t require sprawling distributed systems to be useful and production-ready. By constraining everything to what fits in a tiny portable package, MolnOS enables deployment scenarios that are impractical with traditional cloud platforms—edge devices, offline environments, air-gapped networks—while remaining understandable without specialized expertise.