GINI — gBuilder 6.0

A visual lab for computer networks, cloud computing, and operating systems — draw a system, press Run, and it comes to life as real containers (and a real xv6 kernel) you can inspect, drive, and observe.

💬 Join the community: GINI Discord — questions, help, and discussion.

GINI lets students and instructors build a topology on a canvas, then launches it as honest, running infrastructure on Docker: a real C router that actually forwards packets, a real OpenFlow controller programming a real switch, and real cloud services (databases, object stores, message queues, dashboards) discoverable by name — plus a real xv6 operating-system kernel you can watch and extend in a visual Machine Lab. A built-in AI tutor — GINI — explains what's on the canvas, animates how packets flow, and can scaffold whole working systems from a one-line description.

It's designed to anchor three courses:

• Computer Networks — switches, routers, subnets, firewalls, and real OpenFlow SDN.
• Cloud Computing — VPC-style networking, managed services, autoscaling, observability.
• Operating Systems — a real xv6 (RISC-V) kernel in a visual Machine Lab: watch the scheduler, system calls, traps, virtual memory, and the file system live, then extend the kernel yourself with shadows — a novel way to drop your own code into a running xv6 machine to experiment (fix the scheduler, add a syscall) without forking the kernel.

gBuilder 6.0 is the modern rewrite of the classic GINI Toolkit. The original Python 2.7 / PyQt4 / SCons app lives under legacy/ for reference.

Highlights

• Visual builder — a fast PySide6/Qt 6 canvas with a searchable palette of ~40 networking and cloud elements, theming, save/load, and an inspector.
• It actually runs — Run compiles the canvas to a Docker Compose project and brings it up. Machines, routers, switches, controllers, and cloud services all start as containers.
• The real C gRouter — the genuine GINI router (built with zig cc), forwarding packets over a portable user-space fabric. No kernel modules, no privileges.
• Real SDN — drop an OpenFlow Controller + OpenVSwitch; GINI runs POX (Python 3) programming the gRouter in OpenFlow-1.0 switch mode. Watch flows install on the first packet, then forward at wire speed.
• Cloud services as containers — MinIO, PostgreSQL, Redis, MongoDB, RabbitMQ, Kafka (Redpanda), NATS, nginx, Traefik, Prometheus, Grafana, Jaeger, Fortio, and more — each a real, off-the-shelf image reachable by service name.
• Live observability — drop Metrics + Dashboards and GINI auto-wires cAdvisor → Prometheus → Grafana with a prebuilt dashboard. Generate load and watch the graphs move.
• A real OS to hack — a genuine xv6 kernel in a visual Machine Lab (scheduler, system calls, traps, virtual memory, file system — all live over the serial, no gdb), plus shadows: drop your own code into a running xv6 machine for experiments and graded assignments, no kernel fork required.
• GINI AI — an in-app tutor with Explain, Tutor, and Wizard modes. Ask it to explain a device, trace a path, or describe a system you want and it lays out a working blueprint. Runs against a local LLM (Ollama) or fully offline.

Requirements

• Python 3.10+ (3.12 recommended). The Qt 6 GUI — PySide6 plus QtWebEngine (for the embedded Desktop / OS-Zoo screens) — installs automatically as a dependency; you never install Qt separately, whichever install route you pick.
• A container runtime — Docker, or Colima/Podman (gini-setup detects it and can help install it) — needed to Run topologies. You can explore fully in Demo mode without one.
• Works on macOS, Linux, and Windows. Optional: a local Ollama model for richer GINI AI answers.

Install

There are two ways to install, both fully supported — pick one (don't mix the two; see Troubleshooting). Either way the Qt GUI (PySide6 + QtWebEngine) is pulled in automatically.

1. From source — the latest code

Recommended if you want the newest features, plan to build the xv6 kernel image yourself, or want to contribute. You track main, so you always have the freshest bits.

# in your clone of the repo:
cd frontend-ng
pip install -e .              # editable install; PySide6 + QtWebEngine come with it
gini-setup                    # brings in the container runtime + images (one time)
gbuilder                      # launch

2. Pre-compiled package — the simplest, most stable

The hands-off route. It may be a version or two behind main, but it's the more stable, "just install and go" option — good for students and classroom setups.

pipx install gini-toolkit     # the app, isolated. `pip install gini-toolkit` also works.
gini-setup                    # brings in the container runtime + images (one time)
gbuilder                      # launch

Either way, gbuilder opens immediately — build, save, and explore topologies, with the AI tutor and everything in Demo mode working right away. Live Run (real containers) lights up once gini-setup finishes. After upgrading (git pull for source, or pipx upgrade gini-toolkit for the package), re-run gini-setup --update to refresh images.

No pipx? Install it once (brew install pipx on macOS, or pip install pipx), or use pip install gini-toolkit inside a virtual environment.

brew install colima docker
colima start --cpu 2 --memory 4 --disk 30

# https://docs.docker.com/engine/install/ for your distro, then:
sudo usermod -aG docker $USER      # log out / back in afterwards

winget install -e --id Docker.DockerDesktop

# extra dev tooling (tests, linters) on top of the source install:
cd frontend-ng && pip install -e ".[dev]"

# build the container images yourself instead of pulling them
# (needed to hack the xv6 kernel via shadows):
docker build -t gini-xv6:latest backend/xv6      # + oszoo / grouter / pox

Your first topology

• Place a device by dragging it from the palette onto the canvas.
• Connect two devices: click the Connect tool in the toolbar (the link icon), then click the first device and then the second — a link appears. Click the tool again (or press Esc) to leave Connect mode. You can also ask GINI: "connect R1 and S1".
• Run the topology with the ▶ button.

Once it's running:

• Double-click a machine to open a shell; a service with a web UI (Grafana, MinIO …) to open its dashboard; a router to open the Router Lab.
• Right-click any node for Open console, Log in, View logs, or Delete.
• The console log prints each running service's web URL.

GINI AI

The right-hand Ask GINI panel is a teaching assistant that always sees the live canvas. Modes are toggle buttons; the toolbar shows the current mode and whether GINI is thinking.

• Explain — click any device and GINI explains it on the canvas (spotlight, callouts, animated packet flows). It also explains palette elements ("when do I use a switch vs a hub?").
• Tutor — overlays highlights and animations as it teaches.
• Wizard — describe what you want ("something I can watch under load", "a web app with a database") and GINI matches a curated, guaranteed-to-work recipe and lays it out with one click. The model only selects and explains; the building is deterministic, so even a small local model can't produce a broken topology.

Connect a model by pointing GINI at Ollama:

export GINI_LLM_URL=http://localhost:11434
export GINI_LLM_MODEL=llama3.1        # or gemma, qwen, …
python -m gini

Without a model, GINI still builds, inspects, traces paths, and ranks recipes deterministically.

Software-Defined Networking

The SDN stack is the original GINI design, made real:

• OpenVSwitch element → the gRouter launched in --openflow mode (a real OpenFlow 1.0 switch).
• OpenFlow Controller element → a POX (gar, Python 3) container running an app you choose from the inspector (l2_learning, hub, or the classic of_tutorial).

Draw Controller → OVS → hosts, Run, and ping between hosts: the first packet misses the flow table → goes up to POX → a flow is installed → the rest forward in the datapath. You can watch flows appear with openflow entry all in the OVS console, and the controller's decisions in its logs.

Cloud service catalog

Each of these palette elements runs as a real container, reachable by name on the lab's network (cloud-style service discovery):

Compute elements (Instance, Container) run as plain containers on the same network, so a program inside them reaches services by name (psql -h database1, http://objectstore1:9000).

Repository layout

frontend-ng/        gBuilder 6.0 — PySide6 app (domain · ui · agent · runtime · services)
backend/
  src/grouter/      the real C gRouter (~20k lines) incl. OpenFlow/SDN mode
  grouter-build/      C build + Dockerfile (gini-grouter) + e2e forwarding tests
  sdn/              POX (gar) controller + Dockerfile (gini-pox)
legacy/             the original Python 2.7 / PyQt4 GINI, kept for reference
ARCHITECTURE.md     what's active vs legacy, and how it fits together

See ARCHITECTURE.md for the full map.

Testing

cd frontend-ng
pytest                                   # ~95 tests
# headless / CI:
QT_QPA_PLATFORM=offscreen pytest

The gRouter has end-to-end forwarding proofs under backend/grouter-build/tests/ (forward_test.py, multihop_test.py, …), runnable against a built grouter binary.

Status

gBuilder 6.0 is under active development. Working today: the visual builder, real packet forwarding through the C gRouter (single- and multi-router), OpenFlow SDN (POX + gRouter), the cloud service catalog, observability auto-wiring, and the GINI AI tutor with Explain / Tutor / Wizard modes. On the roadmap: configuring services from the inspector, VPC-level isolation, a managed Kubernetes element, and more Wizard recipes.

License & contact

GINI is free software — see COPYING for copyright information. Questions, bugs, or ideas: open an issue on this repository, or email maheswar@cs.mcgill.ca.