Qube

Features

• ✨ Lightweight and fast container runtime
• 🔒 Linux namespace isolation (PID, Mount, Network, IPC, UTS)
• 📊 CGroups v2 resource management (memory, CPU)
• 🚀 Simple CLI interface
• 🌐 REST API with WebSocket support
• 🐳 Docker-like workflow
• 📦 Prebuilt container images
• 🔧 QML configuration file support

Quick Start

Prerequisites

# Install Go 1.21+
sudo apt-get install golang-1.21  # Ubuntu/Debian
sudo pacman -S go                   # Arch/CachyOS

# Install dependencies
sudo apt-get install -y build-essential tar rsync

Build & Install

# Clone repository
git clone https://github.com/Voyrox/Qube
cd Qube

# Build and install (Recommended for all users)
make install

# Or use build scripts
./scripts/build-go.fish --install  # Fish shell
./scripts/build-go.sh --install    # Bash

Quick Example

# Start the daemon
sudo systemctl start qubed

# Run a Node.js container
sudo qube run --image Voyrox:nodejs:1.0.0 --ports 3000 --cmd "npm install && npm start"

# List running containers
sudo qube list

# Pull an image
sudo qube pull Voyrox:nodejs:1.0.0

# View container info
sudo qube info <container_name>

# Stop a container
sudo qube stop <container_name>

Build Commands

make build    # Build binary
make install  # Build and install
make clean    # Clean build artifacts
make test     # Run tests
make daemon   # Run daemon in debug mode
make deps     # Download dependencies
make fmt      # Format code
make lint     # Lint code
make release  # Build for multiple platforms

Usage

Run Container

# Basic usage
sudo qube run --image <image> --cmd "<command>"

# With ports and network isolation
sudo qube run --image Voyrox:nodejs:1.0.0 --ports 3000 --isolated --cmd "node server.js"

# With environment variables
sudo qube run --image Voyrox:python:1.0.0 --env "DEBUG=true" --cmd "python app.py"

# With volume mounts
sudo qube run --image Voyrox:rust:1.0.0 --volume /host/path:/container/path --cmd "cargo run"

Using QML Configuration

Create qube.yml:

container:
  system: Voyrox:nodejs:1.0.0
  ports:
    - "3000"
  cmd:
    - npm install
    - node index.js
  isolated: false
  environment:
    API_KEY: "your-key-here"
  volumes:
    - host_path: "/data"
      container_path: "/app/data"

Run with:

sudo qube run

Available Commands

qube daemon         # Start daemon
qube run           # Run container
qube list          # List containers
qube stop <id>     # Stop container
qube start <id>    # Start container
qube delete <id>   # Delete container
qube eval <id>     # Execute command in container
qube info <id>     # Show container info
qube snapshot <id> # Create snapshot

Prebuilt Images

Check out available images at: Qube Hub

API Endpoints

GET  /list              # List containers
POST /stop              # Stop container
POST /start             # Start container
POST /delete            # Delete container
POST /info              # Container info
GET  /images            # List images
GET  /volumes           # List volumes
WS   /eval              # WebSocket execution

Development

# Format code
make fmt

# Run linter
make lint

# Run tests
make test

# Build with race detector
make dev

# Start daemon in debug mode
sudo qube daemon --debug

System Requirements

• Linux kernel 3.10+
• CGroups v2 support
• Root privileges
• Go 1.21+ (for building)

Troubleshooting

Permission Denied

# Qube requires root
sudo qube <command>

CGroup Errors

# Check cgroup version
mount | grep cgroup

# Should show cgroup2

Build Errors

# Clean and rebuild
make clean
make deps
make build

Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Format code (make fmt)
4. Run tests (make test)
5. Commit changes (git commit -m 'Add amazing feature')
6. Push to branch (git push origin feature/amazing-feature)
7. Open Pull Request

License

See LICENSE file

Credits

• Qube team (Voyrox and contributors)
• Originally written in Rust, rewritten in Go for improved development experience

Links

• Documentation
• Issues
• Discussions