Vyoma is a production-grade Micro-VM manager. It combines the blazing speed and security of Cloud Hypervisor with the beloved developer experience of Docker.

Spin up secure, isolated VMs in milliseconds using standard OCI (Docker) images. No heavy kernels, no complex QEMU flags—just code.

• Docker UX: Familiar commands: run, ps, logs, exec.
• Vyoma Swarm: Built-in clustering with Mesh Networking (VXLAN) and deterministic IP allocation.
• Vyoma Compose: Orchestrate stacks with vyoma-compose.yml.
• Web Dashboard: Built-in visual management UI (bundled in Daemon, accessible at http://localhost:3000).
• VS Code Extension: Manage VMs directly from VS Code.
• Self-Contained: .deb and .rpm packages bundle all dependencies (Cloud Hypervisor, CNI plugins, UI).
• Persistence: Volume mounts (virtiofs) and Port Mapping.
• Snapshotting: Instant VM snapshots and State Teleportation.
• Secure by Default: Daemon runs as vyoma user with kernel capabilities, socket permissions 0660.

• Linux kernel 5.10+ with KVM, cgroups v2, and TUN/TAP enabled.
• A user with sudo access.

Go to the Releases Page and download the latest package for your distro.

Debian/Ubuntu:

sudo apt install ./vyoma_2.8.0_amd64.deb

Fedora/RHEL/CentOS:

sudo rpm -i vyoma-2.8.0-1.x86_64.rpm

After installation, your user needs to be added to the vyoma group to access the daemon socket:

# Log out and log back in, or run:
newgrp vyoma

Why is this needed? The CLI connects to the daemon via Unix socket at /run/vyoma/vyoma.sock with permissions 0660 (owned by vyoma:vyoma). Without being in the vyoma group, the socket access is denied.

What's Installed:

• /usr/bin/vyomad: The Daemon (Run via Systemd).
• /usr/bin/vyoma: The CLI Tool.
• /usr/bin/cloud-hypervisor: Bundled VMM binary.
• /usr/lib/vyoma/cni/bin/: CNI plugins for networking.
• /usr/lib/vyoma/ui/: Web dashboard (served at http://localhost:8080).
• /etc/systemd/system/vyomad.service: Service definition.

vyoma doctor

This utility checks for KVM (/dev/kvm), tun/tap support, and daemon connectivity.

For a complete reference of all 20+ commands, see COMMANDS.md.

• Run a VM:

  vyoma run ubuntu:latest --vcpu 2 --memory 1024 -p 8080:80

• List VMs: vyoma ps
• Logs: vyoma logs -f <vm_id>
• Shell Access: vyoma exec <vm_id> /bin/bash
• Stop/Remove: vyoma stop <vm_id>, vyoma rm <vm_id>
• Pause/Resume: vyoma pause <vm_id>, vyoma resume <vm_id>

Vyoma uses CNI for robust networking.

• List Networks: vyoma network ls
• Create Network: vyoma network create my-net --subnet 10.10.0.0/16

Turn multiple machines into a single mesh.

1. Initialize Seed (Leader):

   vyoma swarm init
   # OR specify IP: vyoma swarm init --advertise-addr 192.168.1.10

2. Join Worker:

   vyoma swarm join <SEED_IP>

3. List Nodes: vyoma swarm ls

Swarm ensures unique Subnet Leases (e.g., 10.42.1.0/24 for Node 1) and routes traffic transparently over VXLAN.

Define complex stacks using vyoma-compose.yml:

version: "1.0"
services:
  web:
    image: nginx:alpine
    ports: ["80:80"]
  db:
    image: postgres:15
    cpus: 2

• Deploy: vyoma up -d
• Teardown: vyoma down

The Vyomafile is used to build custom images via vyoma build.

# Start from a base image (Docker Hub or local)
FROM alpine:3.18

# Run commands to install packages or setup environment
RUN apk add --no-cache python3 curl

# Copy files from host execution context to VM
COPY app.py /app/app.py
COPY config.json /etc/config.json

Note: CMD, ENV, and ENTRYPOINT are not yet supported. VMs start with /bin/sh init unless overridden.

Use vyoma-compose.yml to orchestrate multi-VM stacks.

version: "1.0"
services:
  web:
    image: nginx:alpine
    ports: 
      - "8080:80"        # Host:VM
    volumes:
      - "./html:/var/www" # Host:VM (Requires virtiofsd)
    cpus: 1              # vCPU limit
    memory: 512          # Memory limit in MiB
    depends_on:
      - db

  db:
    build: 
      context: ./database
      vyomafile: Vyomafile
    environment:         # Environment variables (WIP)
      POSTGRES_PASSWORD: secret

Note: Custom networks: are not supported in Compose v1.0. Services communicate via the default bridge using their Service Name as hostname (DNS enabled).

Vyoma is designed to be "Batteries Included", but some advanced features need helpers.

Primary Dependencies (Bundled in Package):

• Cloud Hypervisor: The VMM (Virtual Machine Monitor).
• CNI Plugins: For VM networking (bridge, host-local IPAM).
• Web UI: Dashboard bundled at /usr/lib/vyoma/ui.
• KVM: Kernel-based Virtual Machine. MUST be enabled in BIOS/OS (/dev/kvm).
• Systemd: Manages the vyomad daemon lifecycle.

Optional Dependencies (Install Manually):

• Virtiofsd: REQUIRED for Volume Mounts (-v).
  • Ubuntu/Debian: sudo apt install virtiofsd
  • Fedora: sudo dnf install virtiofsd
  • Manual: Download binary from GitLab and place in $PATH or /usr/bin.

Privilege Model:

• Daemon (vyomad): Runs as vyoma user with kernel capabilities (CAP_NET_ADMIN, CAP_SYS_ADMIN, CAP_NET_RAW, CAP_SETUID, CAP_SETGID).
• Socket: /run/vyoma/vyoma.sock with permissions 0660 (root:vyoma).
• Client (vyoma): Runs as User (must be in vyoma group).
• User Must Logout/Login Once: After installation, log out and back in for group membership to take effect.

For developers contributing to Vyoma, please refer to:

• CLI Reference for full CLI reference.

We welcome contributions! Please feel free to open issues or PRs.

Apache 2.0 License.