How mfernd/cloudlet works
Project Type and Purpose
• Cloudlet is a lightweight FaaS (Function-as-a-Service) orchestration system written in Rust.
• It comprises several Rust crates (workloads):
• CLI (user-facing client)
• API (HTTP server)
• VMM (virtual machine manager using gRPC)
• Agent (runs inside the VM, also gRPC)
• FS-gen (initramfs and image builder)
• shared-models and proto definitions (gRPC schemas)
• The system let users submit code (Rust, Python, Node), spins up a VM, builds and runs it inside the VM’s Agent, and streams back results.
High-Level File Structure Analysis
• Top-level Cargo workspace: Cargo.toml, Justfile, proto/, assets/, tools/
• src/agent/: code builder & runner inside the VM
• src/api/: HTTP→gRPC façade for clients
• src/cli/: command-line interface for end users
• src/fs-gen/: kernel/initramfs/image generation tooling
• src/vmm/: hypervisor orchestration, gRPC server & client
• src/shared-models and proto/: shared message definitions
Key Architecture Insights from README
• Flow: CLI → HTTP to API → gRPC to VMM → VM boot → Agent gRPC → code build & run → response streams back
• Components communicate over HTTP (CLI↔API) and gRPC (API↔VMM, VMM↔Agent)
• Tools/ contains shell scripts to build Linux kernel & rootfs for the VM
Components
a. External Client
• CLI binary (src/cli/)
b. API Service
• HTTP server (src/api/)
c. VMM Service
• gRPC server (src/vmm/)
• Hypervisor module (VM creation, networking, epoll)
d. Agent inside VM
• Agent gRPC server (src/agent/)
• Workload builder & runner
e. Image Generation Tool
• FS-gen (kernel/initramfs builder)
f. Shared Models & Proto
• Shared message definitions (proto/, src/shared-models/)
g. Underlying Infrastructure
• Host OS capabilities (cap_net_admin, iptables)
• Virtual networking (tuntap, virtio)
Interactions and Data Flow
• HTTP request from CLI → API
• API translates HTTP to gRPC → VMM
• VMM invokes host hypervisor APIs to create VM
• VMM loads kernel + initramfs (built by FS-gen) into VM
• VM boots into Agent binary
• VMM calls Agent gRPC endpoint to send workload config & source path
• Agent compiles & runs code inside VM, streams stdout/stderr back via gRPC
• VMM relays gRPC stream → API → HTTP response → CLI
Architectural Patterns & Principles
• Microservice-style Rust crates communicating over defined interfaces (HTTP, gRPC)
• Clear separation of concerns:
• CLI only handles user I/O
• API handles external HTTP endpoints and authentication/validation
• VMM handles VM lifecycle & networking
• Agent handles in-VM build/run isolation
• FS-gen decouples image creation
• Shared Protobuf definitions ensure consistency across service boundaries
• Use of capabilities (capsh, iptables) for secure VM networking