Skip to content

akkarit/glidex

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

13 Commits
crates
crates
 
 
.gitignore
.gitignore
 
 
Cargo.lock
Cargo.lock
 
 
Cargo.toml
Cargo.toml
 
 
README.md
README.md
 
 
install.sh
install.sh
 
 

Repository files navigation

Glidex

A Rust-based control plane for managing microVMs with support for multiple hypervisors including Firecracker and Cloud-Hypervisor.

   _____ _ _     _
  / ____| (_)   | |
 | |  __| |_  __| | _____  __
 | | |_ | | |/ _` |/ _ \ \/ /
 | |__| | | | (_| |  __/>  <
  \_____|_|_|\__,_|\___/_/\_\

Features

  • Multi-hypervisor support - Control both Firecracker and Cloud-Hypervisor VMs through a unified interface
  • REST API for VM lifecycle management (create, start, stop, pause, delete)
  • Web UI - Modern Leptos-based web interface for VM management
  • Interactive CLI (gxctl) with command history and tab completion
  • Interactive console - connect to VM serial console with full I/O support
  • Console logging - persistent logs of all VM console output
  • Multi-client support - multiple CLI sessions can connect to the same VM console

Quick Start

Installation

# Clone the repository
git clone https://github.com/yourusername/glidex.git
cd glidex

# Run the installer (installs Rust, Firecracker, builds the project)
./install.sh

The installer will:

  1. Install Rust (if not present)
  2. Download and install Firecracker v1.14.0
  3. Build the Glidex binaries
  4. Optionally download sample kernel and rootfs images to ~/.glidex/

For Cloud-Hypervisor support, install it separately:

# Download Cloud-Hypervisor (check https://github.com/cloud-hypervisor/cloud-hypervisor/releases for latest)
wget https://github.com/cloud-hypervisor/cloud-hypervisor/releases/download/v44.0/cloud-hypervisor-static
chmod +x cloud-hypervisor-static
sudo mv cloud-hypervisor-static /usr/local/bin/cloud-hypervisor

Manual Installation

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Build the project
cargo build --release

# Binaries are in target/release/
#   - glidex-control-plane (server)
#   - gxctl (CLI)

Running

  1. Start the control plane server:
cargo run --bin glidex-control-plane

The server listens on http://localhost:8080 by default.

  1. Option A: Start the Web UI:
cd crates/glidex-ui
cargo leptos watch

Open http://localhost:3000 in your browser.

  1. Option B: Start the CLI:
cargo run --bin gxctl
  1. Create and start a VM (via CLI):
gxctl> create
VM name: my-vm
vCPU count [1]: 2
Memory (MiB) [512]: 1024
Kernel image path [~/.glidex/vmlinux.bin]:
Root filesystem path [~/.glidex/rootfs.ext4]:
Kernel arguments (optional):
Hypervisor [firecracker/cloudhypervisor] (default: cloudhypervisor):

gxctl> start my-vm
  1. Connect to the VM console:
gxctl> connect my-vm

Press Ctrl+] to detach from the console.

  1. View console logs:
gxctl> log my-vm

CLI Commands

Command Description
list List all VMs
get <name|id> Show VM details
create Create a new VM (interactive)
start <name|id> Start a VM
stop <name|id> Stop a VM
pause <name|id> Pause a running VM
connect <name|id> Connect to VM console (interactive)
log <name|id> Show VM serial console log
delete <name|id> Delete a VM
health Check API server health
help Show available commands
exit Exit the CLI

REST API

Endpoints

Method Endpoint Description
GET /health Health check
GET /vms List all VMs
POST /vms Create a new VM
GET /vms/{id} Get VM details
DELETE /vms/{id} Delete a VM
POST /vms/{id}/start Start a VM
POST /vms/{id}/stop Stop a VM
POST /vms/{id}/pause Pause a VM
GET /vms/{id}/console Get console connection info

Create VM Request

{
  "name": "my-vm",
  "vcpu_count": 2,
  "mem_size_mib": 1024,
  "kernel_image_path": "/path/to/vmlinux.bin",
  "rootfs_path": "/path/to/rootfs.ext4",
  "kernel_args": "console=ttyS0 reboot=k panic=1 pci=off",
  "hypervisor": "cloudhypervisor"
}

The hypervisor field is optional and defaults to "cloudhypervisor". Supported values:

  • "cloudhypervisor" - Use Cloud-Hypervisor (default)
  • "firecracker" - Use Firecracker hypervisor

Example: Create and Start a VM with curl

# Create a VM
curl -X POST http://localhost:8080/vms \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test-vm",
    "vcpu_count": 2,
    "mem_size_mib": 512,
    "kernel_image_path": "/home/user/.glidex/vmlinux.bin",
    "rootfs_path": "/home/user/.glidex/rootfs.ext4"
  }'

# Start the VM
curl -X POST http://localhost:8080/vms/{vm-id}/start

# List VMs
curl http://localhost:8080/vms

Architecture

┌─────────────────────────────────────────────────────────────┐
│                   glidex-ui (Web UI)                        │
│  - Leptos SSR + Hydration                                   │
│  - Dashboard, VM management                                 │
│  - Real-time status updates                                 │
└─────────────────┬───────────────────────────────────────────┘
                  │ HTTP (REST API)
┌─────────────────┼───────────────────────────────────────────┐
│                 │        gxctl (CLI)                        │
│                 │  - Interactive shell                      │
│                 │  - Connects to console Unix socket        │
└─────────────────┼───────────────────────────────────────────┘
                  │ HTTP / Unix Socket
┌─────────────────▼───────────────────────────────────────────┐
│              glidex-control-plane (Server)                  │
│  - REST API (Axum)                                          │
│  - VM state management                                      │
│  - Hypervisor abstraction layer                             │
│  - Console proxy (PTY ↔ Unix socket)                        │
│  - Console logging                                          │
│  - Persistence (ReDB)                                       │
└─────────────────┬───────────────────────────────────────────┘
                  │ Unix Socket (Hypervisor API)
        ┌─────────┴─────────┐
        ▼                   ▼
┌───────────────┐   ┌───────────────────┐
│  Firecracker  │   │  Cloud-Hypervisor │
│  - microVM    │   │  - microVM        │
│  - KVM-based  │   │  - KVM-based      │
└───────────────┘   └───────────────────┘

Hypervisor Abstraction

The control plane uses a trait-based abstraction to support multiple hypervisors:

hypervisor/
├── mod.rs              # Hypervisor and HypervisorProcess traits
├── firecracker.rs      # Firecracker implementation
└── cloud_hypervisor.rs # Cloud-Hypervisor implementation

Both hypervisors implement the same interface:

  • configure() - Configure VM with CPU, memory, kernel, and disk
  • start() - Boot the VM
  • pause() - Pause the VM
  • resume() - Resume a paused VM
  • kill() - Terminate the VM process

Console Architecture

For each running VM (Firecracker):

  • A PTY (pseudo-terminal) pair is created
  • The hypervisor's stdin/stdout/stderr connect to the PTY slave
  • A background thread reads from the PTY master and:
    • Writes all output to a log file (/tmp/{hypervisor}-{id}.log)
    • Broadcasts to connected clients via Unix socket (/tmp/{hypervisor}-{id}.console.sock)
  • Multiple clients can connect simultaneously

For Cloud-Hypervisor, console output is captured via the --console file option.

Requirements

  • Linux (both hypervisors only support Linux)
  • KVM enabled (/dev/kvm accessible)
  • Rust 1.85+ (for building)
  • Firecracker 1.14.0+ (for Firecracker VMs)
  • Cloud-Hypervisor 44.0+ (optional, for Cloud-Hypervisor VMs)

Enabling KVM

# Check if KVM is available
ls -la /dev/kvm

# Add your user to the kvm group
sudo usermod -aG kvm $USER

# Log out and back in for the change to take effect

Project Structure

glidex/
├── Cargo.toml                    # Workspace root
├── install.sh                    # Installation script
├── README.md
└── crates/
    ├── glidex-control-plane/     # Control plane server
    │   ├── src/
    │   │   ├── main.rs           # Server entry point
    │   │   ├── api.rs            # REST API routes and handlers
    │   │   ├── models.rs         # Data structures (VM, VmConfig, etc.)
    │   │   ├── state.rs          # VM state management
    │   │   ├── persistence.rs    # ReDB-based persistence
    │   │   ├── hypervisor/       # Hypervisor abstraction layer
    │   │   │   ├── mod.rs        # Traits and HypervisorType enum
    │   │   │   ├── firecracker.rs    # Firecracker backend
    │   │   │   └── cloud_hypervisor.rs # Cloud-Hypervisor backend
    │   │   └── bin/
    │   │       └── gxctl.rs      # CLI client
    │   └── tests/
    │       └── api_tests.rs      # API integration tests
    └── glidex-ui/                # Web UI (Leptos)
        ├── src/
        │   ├── main.rs           # SSR server
        │   ├── app.rs            # Root component
        │   ├── api/              # API client
        │   ├── components/       # UI components
        │   └── pages/            # Page views
        ├── style/                # Tailwind CSS
        └── README.md             # UI documentation

Development

Running Tests

cargo test

Building in Debug Mode

cargo build

Building for Release

cargo build --release

Sample Kernel and RootFS

The installer can download official Firecracker CI images:

  • Kernel: Linux kernel compiled for Firecracker
  • RootFS: Ubuntu-based root filesystem (ext4)
  • SSH Key: Generated key pair for VM access

Files are stored in ~/.glidex/:

~/.glidex/
├── vmlinux.bin    # Linux kernel
├── rootfs.ext4    # Ubuntu root filesystem
├── vm_key         # SSH private key
└── vm_key.pub     # SSH public key

To SSH into a running VM (requires network configuration):

ssh -i ~/.glidex/vm_key root@<vm-ip>

License

MIT

Acknowledgments

About

Glider firecracker extension

Resources

Readme
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages