https://github.com/nexusquantum/nqrust-microvm

Self-hosted Firecracker microVM platform — sub-125ms VMs, Docker-in-VM, serverless functions, and pluggable storage (local, NFS, iSCSI+LVM, TrueNAS, SPDK)
https://github.com/nexusquantum/nqrust-microvm

container containerization functions-as-a-service hypervisor hypervisors nextjs rust serverless

Last synced: 8 days ago
JSON representation

Self-hosted Firecracker microVM platform — sub-125ms VMs, Docker-in-VM, serverless functions, and pluggable storage (local, NFS, iSCSI+LVM, TrueNAS, SPDK)

Host: GitHub
URL: https://github.com/nexusquantum/nqrust-microvm
Owner: NexusQuantum
Created: 2025-09-14T06:06:18.000Z (9 months ago)
Default Branch: main
Last Pushed: 2026-06-08T08:31:13.000Z (10 days ago)
Last Synced: 2026-06-08T10:18:04.598Z (10 days ago)
Topics: container, containerization, functions-as-a-service, hypervisor, hypervisors, nextjs, rust, serverless
Language: Rust
Homepage: https://microvm.nexusquantum.id/
Size: 77.3 MB
Stars: 5
Watchers: 0
Forks: 1
Open Issues: 3
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Roadmap: docs/ROADMAP.md

Awesome Lists containing this project

README

          








**A self-hosted cloud platform powered by Firecracker microVMs**

Boot Linux VMs in under 125ms · Docker containers with hardware isolation


Serverless functions · Web terminal · Real-time metrics · No cloud dependency



  

  

  

  



[**Install →**](#installation) · [**Documentation**](docs/) · [**API Reference**](#api-reference) · [**Report a Bug**](https://github.com/NexusQuantum/NQRust-MicroVM/issues)



---

## Screenshots

  

    

    

  

  

    _{Virtual Machines — create, manage, and monitor all your microVMs}

    _{VM detail — 7-tab interface: overview, terminal, metrics, storage, network, snapshots, config}

  

  

    

    

  

  

    _{Browser-based xterm.js shell — no SSH client needed}

    _{Live CPU, memory, network, and disk graphs over WebSocket}

  

  

    

    

  

  

    _{Serverless functions — Monaco editor, live execution logs, playground}

    _{One-command TUI installer — guided setup, online and airgapped}

  

---

## Overview

**NQRust-MicroVM** is a production-ready platform for running [Firecracker](https://firecracker-microvm.github.io/) microVMs on your own Linux hardware. Three Rust services and a Next.js 15 frontend — installed in one command.

**Virtual Machines** — Isolated Linux VMs with their own kernel, rootfs, CPU/memory limits, and storage volumes. Browser terminal. Snapshots. Templates for one-click re-deployment.

**Containers** — Docker workloads running *inside* Firecracker VMs. Full Docker API compatibility with hardware-level kernel isolation underneath — container escape is structurally impossible.

**Serverless Functions** — Node.js, Python, or Ruby functions that execute on demand in isolated VMs. Webhook-ready with a built-in code editor and execution playground.

**Pluggable Storage** — Mix-and-match backends from a single UI: local file (zero deps), NFS and SMB/CIFS (auto-mount via the agent), and `iscsi_lvm` (vendor-agnostic per-VM block devices on top of any iSCSI target — Proxmox-equivalent, no per-vendor REST adapter required). Add or remove backends without restarting the manager.

---

## Features

| | Feature | Details |

|---|---|---|

| ⚡ | **Sub-125ms Boot** | Firecracker starts Linux VMs faster than most processes |

| 🖥️ | **Web Terminal** | Full xterm.js shell in the browser via WebSocket — no SSH client needed |

| 📊 | **Real-time Metrics** | Live CPU, memory, network, and disk graphs streamed over WebSocket |

| 🐳 | **Isolated Containers** | Docker-in-VM with full Docker API — hardware-level kernel isolation |

| ⚡ | **Serverless Functions** | Node.js, Python, Ruby — Monaco editor, live logs, interactive playground |

| 📸 | **Snapshots** | Full and differential VM snapshots with instant restore |

| 📦 | **Image Registry** | Kernels, rootfs, and Docker images — import from URL, local path, or DockerHub |

| 🌐 | **Flexible Networking** | NAT, Isolated, Bridged, and VXLAN overlay networks |

| 💾 | **Pluggable Storage** | Local file (default), NFS auto-mount, SMB/CIFS, vendor-agnostic iSCSI+LVM, TrueNAS REST, SPDK vhost-user — add or remove backends from the UI without restart |

| 🔀 | **Port Forwarding** | Route external traffic to services running inside VMs |

| 🏢 | **Multi-Host Clustering** | Add agent nodes to a shared manager — scale across physical machines |

| 👥 | **RBAC** | Admin / User / Viewer roles, resource ownership, per-user preferences |

| 📋 | **Templates** | Save VM configurations for one-click re-deployment |

| 🔒 | **TUI Installer** | Guided Rust installer — online and fully airgapped, manages systemd services |

---

## Architecture

Four lightweight components coordinate to run your workloads:

| Component | Role | Port |

|---|---|---|

| **Manager** | Central API — VM lifecycle, image registry, networking, storage, RBAC | 18080 |

| **Agent** | Runs on each KVM host, executes Firecracker operations via Unix socket | 9090 |

| **Guest Agent** | Tiny static binary auto-deployed inside every VM, reports metrics and IP | 9000 |

| **Web UI** | Next.js 15 / React 19 dashboard — terminal, metrics, full management | 3000 |

```mermaid

graph TD

    Browser([Browser])

    subgraph Platform["NQRust-MicroVM Platform"]

        UI["Web UI · Next.js 15"]

        Manager["Manager API · Rust · Axum · PostgreSQL"]

        DB[("PostgreSQL")]

        subgraph Host["KVM Host"]

            Agent["Host Agent · Rust"]

            VM1["microVM + Guest Agent"]

            VM2["microVM + Guest Agent"]

        end

    end

    Browser -->|"HTTPS / WebSocket"| UI

    UI -->|"REST API"| Manager

    Manager -->|"SQL"| DB

    Manager -->|"REST"| Agent

    Agent -->|"Unix socket"| VM1

    Agent -->|"Unix socket"| VM2

    VM1 -->|"metrics · IP"| Manager

    VM2 -->|"metrics · IP"| Manager

```

### Network Types

| Type | Description | Best for |

|---|---|---|

| **NAT** | Private subnet, internet via host NAT | Most workloads |

| **Isolated** | Private subnet, no external access | Air-gapped services |

| **Bridged** | VMs appear directly on your LAN | Direct network visibility |

| **VXLAN** | Multi-host overlay tunnel | VMs across physical machines |

### Storage Backends

Each VM picks where its rootfs (and additional disks) live. Backends register from the Add Backend UI and are immediately usable — no manager restart needed. Three are visible by default; three more (vendor-specific) are tucked behind a "Show advanced kinds" disclosure.

| Backend | Visible | Provisioning model | Best for |

|---|---|---|---|

| **`local_file`** | default | Files under `/srv/fc/vms//storage/` | Single-host, dev/demo, no SAN |

| **`nfs`** | yes | Manager delegates `mount.nfs` to the agent; one file per VM under the share | Homelab / NAS-backed setups |

| **`smb`** | yes | Mount any SMB/CIFS share via the agent; one file per VM under the share | NAS / Windows-file-server-backed setups |

| **`iscsi_lvm`** | yes | One LUN on any iSCSI target → LVM VG → per-VM `lvcreate` (Proxmox-equivalent) | Multi-VM on shared block storage, vendor-agnostic |

| **`truenas_iscsi`** | advanced | TrueNAS REST creates per-VM zvol + extent + target | TrueNAS users wanting native ZFS snapshots and thin provisioning |

| **`iscsi`** (generic) | advanced | Pre-cut LUN, 1 VM per LUN — passthrough only | Legacy LUN passthrough |

| **`spdk_lvol`** | advanced | NVMe vhost-user direct, future clustering primitive | High-throughput single-host |

---

## Installation

The `nqr-installer` is a guided Rust TUI that provisions everything — KVM access, networking bridge, PostgreSQL, systemd services, and platform configuration.

### Online

```bash

curl -fsSL https://github.com/NexusQuantum/NQRust-MicroVM/releases/latest/download/install.sh | sudo bash

```

### Airgapped

```bash

# On a connected machine — download the installer binary

curl -fsSL -o nqr-installer \

  https://github.com/NexusQuantum/NQRust-MicroVM/releases/latest/download/nqr-installer-x86_64-linux-musl

chmod +x nqr-installer

# Transfer to the target host and run

scp nqr-installer user@target-host:/tmp/

ssh user@target-host sudo /tmp/nqr-installer install

```

The TUI walks through mode selection, network configuration, pre-flight checks, and live installation progress. Full walkthrough: [Installation Guide](docs/content/docs/getting-started/installation.md).

### Installation Modes

| Mode | Components | Use case |

|---|---|---|

| **Production** | Manager + Agent + UI | Single host, all-in-one |

| **Manager Only** | Manager | Control plane in a multi-host setup |

| **Agent Only** | Agent | Worker node joining an existing manager |

| **Minimal** | Manager + Agent | Headless / no web UI |

### System Requirements

| | Minimum | Recommended |

|---|---|---|

| **CPU** | x86_64 with KVM (Intel VT-x / AMD-V) | — |

| **RAM** | 4 GB | 8 GB+ |

| **Disk** | 20 GB free | 50 GB+ |

| **OS** | Ubuntu 22.04, Debian 11 | Ubuntu 24.04 LTS |

### Default Credentials

After installation, open `http://:3000` and log in with **`root` / `root`**. Change the password immediately via **Settings → Account**.

---

## Quick Start

### Create your first VM

1. Open **Registry** → import a kernel and rootfs (URL, local path, or DockerHub)

2. Go to **Virtual Machines → Create VM** and follow the 6-step wizard

3. Click the **Terminal** tab for instant browser-based shell access

4. Explore **Metrics** for live CPU, memory, network, and disk graphs

### Deploy a serverless function

1. Go to **Functions → New Function**

2. Choose a runtime (Node.js, Python, Ruby) and write code in the Monaco editor

3. Use the **Playground** to send test payloads and view live execution logs

### Run a Docker container

1. Go to **Containers → New Container**

2. Enter any Docker image name — the platform provisions a dedicated Firecracker VM with Docker runtime

3. Each container runs in complete VM isolation with its own kernel

---

## API Reference

Interactive Swagger UI is available while the manager is running:

```

http://:18080/swagger-ui/

```

Every operation available in the UI is also accessible via the REST API.

---

## Development

See [CLAUDE.md](CLAUDE.md) for full development setup, architecture details, and code conventions.

```bash

# Start PostgreSQL

./scripts/dev-up.sh

# Build all services

cargo build

# Start the frontend dev server

cd apps/ui && pnpm install && pnpm dev

```

Default dev URLs: UI at `http://localhost:3000`, Manager API at `http://localhost:18080`.

---

## Contributing

1. Fork the repository

2. Create a feature branch: `git checkout -b feature/your-feature`

3. Commit your changes: `git commit -m 'Add your feature'`

4. Push and open a Pull Request

---

## License

Distributed under the **GNU Affero General Public License v3.0**. See [LICENSE](LICENSE) for details.



  _{Built with Rust and caffeine by the Nexus team.}

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/nexusquantum/nqrust-microvm

Awesome Lists containing this project

README