GnosisLab-VM

An isolated scientific research environment with protected research records and experiment execution

GnosisLab-VM images can run on Linux, Windows and macOS^*

Build a sealed KVM lab template once — clone a disposable research environment for each workflow.

Requirements · Build locally · Published image · Other hypervisors · Operations · MCP · Comparison · Security · Citation · GnosisLab · Paper · Discord · Docs

^* Platform compatibility disclaimer: Cross-platform availability refers to running or emulating a compatible Linux VM image, not to identical support for every host OS. The automated build, clone, import, management and QEMU guest-agent data-transfer scripts currently target x86-64 Linux with KVM/libvirt. On Windows and Intel-based macOS, a compatible x86-64 hypervisor can use a converted disk image or appliance; on Apple Silicon, the existing x86-64 image requires emulation and can be much slower. Windows ARM64 and native ARM64 guest images are not currently supported. Non-KVM configurations have not undergone the same functional or security validation. See Running without KVM for details.

---

GnosisLab-VM provides a KVM/libvirt virtual machine for running GnosisLab and AI-assisted or human-led experiments with additional isolation between the agent interface, trusted scientific services, and execution of potentially untrusted code. It includes a VM template builder, clone/import workflows, containerized execution environments, data-transfer tooling, and security/readiness checks.

GnosisLab is the scientific research-process runtime. GnosisLab-VM is its optional virtualized environment. The core GnosisLab services can run without this repository. GnosisLab-VM does not orchestrate agents and does not guarantee containment against every threat.

Why this edition exists: General-purpose agent sandboxes primarily constrain execution and access. GnosisLab-VM combines isolation with GnosisLab's scientific-process records, evidence capture, experiment management and checks against actual execution. Its three guest trust zones separate interactive agents, trusted scientific services and untrusted experiment code. These controls make research activity more inspectable; they do not guarantee scientific truth or complete containment.

What it provides

Layer	Purpose
Host	Linux host running KVM/QEMU and libvirt (qemu:///system); builds, clones, imports, and controls VM instances.
Driver zone	Guest desktop and agent clients such as OpenCode/VSCodium, under guest user lab.
Trusted zone	GnosisLab MCP services and scientific state, running in a dedicated rootless Podman container under mcp.
Experiment zone	Separate, restricted Podman container under exp for generated or untrusted experiment code.
Data movement	Host-initiated import/export via the QEMU guest agent; no guest-accessible host filesystem by default.

The five GnosisLab services are Agora, Arete, Zetesis, Episteme, and Anamnesis. This environment separates research records from experimental execution, while GnosisLab itself supplies scientific state, provenance, and methodological controls.

Security boundary: KVM is the host isolation layer. Containers, accounts, filesystem permissions, firewall rules, and constrained execution wrappers provide additional separation inside the guest. Agent-supplied code and returned artifacts remain untrusted. Anyone with guest administrative credentials can defeat in-guest boundaries; host security depends on QEMU, libvirt, the host kernel, configuration, and patching. See Security and the guest security manual.

How GnosisLab-VM compares

GnosisLab-VM is a scientific research environment, whereas NVIDIA OpenShell, Docker Sandboxes and E2B primarily provide agent/code isolation and execution infrastructure. They can potentially host GnosisLab with additional integration. The table evaluates native, documented capabilities, not theoretical extensibility or relative security strength.

Feature provided out of the box	GnosisLab-VM	OpenShell	Docker Sandboxes	E2B
GnosisLab scientific-process services included	✅	—	—	—
Structured hypotheses, trials and research decisions	✅	—	—	—
Execution evidence tied to scientific research records	✅	—	—	—
Separate protected scientific services and untrusted experiment zone	✅	—	—	—
Preconfigured interactive scientific research desktop	✅	—	🟡	🟡
Full VM/hypervisor isolation available	✅	🟡	✅	✅
Read-only untrusted experiment rootfs	✅	🟡	🟡	🟡
Deny-by-default egress policies	—	✅	✅	—
Provider credentials mediated outside agent workload	—	✅	✅	—
General-purpose sandbox lifecycle SDK/API	—	✅	✅	✅

Legend: ✅ documented native feature; 🟡 optional, partial or backend-dependent; — not a native documented capability. A tick does not establish equal security or feature depth. GnosisLab scientific functionality belongs to the core runtime, which can run independently of this VM edition. OpenShell's VM isolation requires its MicroVM backend. E2B is cloud-oriented.

Where GnosisLab-VM differs: research-process and execution-evidence integration, explicitly separated trusted/experiment zones, a persistent research desktop, disposable full-VM templates and deliberate host-controlled data extraction. Where alternatives lead: fine-grained egress controls, credential mediation, multi-backend APIs and hosted scaling. GnosisLab-VM's experiment zone currently permits public-network egress; security policy must be reviewed before handling confidential inputs.

For a detailed architectural breakdown, further alternatives (Daytona, Kata Containers, Firecracker and gVisor), expanded tickmark matrices, cross-platform limitations and suggested hardening priorities, see Architecture and alternatives.

Requirements

The following are requirements for the Linux/KVM build, import and VM-management tools. Running a prebuilt image under another hypervisor is described below.

• x86-64 Linux host with hardware virtualization enabled and /dev/kvm available.
• Working QEMU/KVM, system libvirt, virsh, virt-install, virt-clone, UEFI firmware (OVMF), and virt-sysprep/libguestfs tooling. The build script can help identify/install missing system packages.
• A Linux Mint ISO or access to the build script's ISO provisioning workflow, plus network access for dependencies (unless using a prepared offline cache).
• Sufficient host CPU, memory, and disk. Defaults in labloop.conf request 16 GiB RAM, 16 vCPUs (subject to host clamping), and the builder provisions a VM disk; adjust to your host before building.
• Sudo access and appropriate local libvirt permissions. Do not run this on a shared or production host without reviewing the isolation assumptions.

Development and build provenance are documented in WORKFLOW.md. This is alpha software, not a production-certified sandbox.

Getting started: build locally

git clone https://github.com/cloudcell/gnosislab-vm.git
cd gnosislab-vm

# Review VM sizing and display settings first (default: 2560x1440 @ 75 Hz).
cat labloop.conf

# Build, prepare and clone a guest.
./00-build-lab-template.sh
./01-prepare-template-for-cloning.sh
./02-create-vm-from-template.sh researcher

A clone is conventionally named lab-vm-researcher. Start it with virsh -c qemu:///system start lab-vm-researcher or through virt-manager. The build and clone scripts perform readiness/security checks; verify the reported results instead of assuming completion means every control passed. A guest XRandR hook applies the configured mode at the LightDM greeter and desktop login; a SPICE viewer with automatic resizing enabled may subsequently request a different mode. Disable View → Scale Display → Auto resize VM with window in virt-manager if you need a fixed 2560×1440 desktop. Display failures are reported as labloop-display diagnostics in the guest journal.

Important credentials: locally built, unsealed templates and their clones initialize lab/lab, followed by a first-login password-change prompt. Published images use sealed accounts and an importer-provisioned one-time credential; a local clone of a previously publication-sealed template also uses a unique one-time password. The one-time credential is recorded in the operator-only <vm>.otp sidecar file alongside the QCOW2. Never publish lab/lab or expose the OTP sidecar. Never publish an unsealed VM image or distribute default credentials. Refer to WORKFLOW.md for release and import details.

Optional offline build: populate and verify the cache using ./selfbuild/prefetch-cache.sh before running LABLOOP_OFFLINE=1 ./00-build-lab-template.sh. Keep caches and downloaded image artifacts out of version control.

Using a published VM image

A historical image distribution location is the Cloudcell LabLoop Hugging Face bucket. That bucket name is a legacy distribution path, not the product name; check availability and publisher authenticity before relying on an image. Images are not hosted in this Git repository.

Download a .qcow2 image and its matching .sha256, verify the digest and, when available, the publisher's authenticated release manifest or signature, then import:

sha256sum -c image.qcow2.sha256
./20-import-lab-vm.sh image.qcow2 researcher

A checksum obtained from the same untrusted source only detects corruption, not a malicious replacement. Review the image provenance and security policy before use.

Running without KVM (VirtualBox, macOS)

The build and import pipeline (00–02, 20) is Linux + KVM/libvirt only — it requires qemu:///system, OVMF, and the QEMU guest agent, none of which exist on VirtualBox or macOS. But a released .qcow2 is a Linux Mint x86-64 virtual disk that may be booted by a compatible alternative hypervisor after conversion or appropriate configuration.

./12-export-image-vmdk.sh <image.qcow2> produces a sparse .vmdk; add --ova to also create a .ova appliance (streamOptimized VMDK and generated OVF descriptor). Run the conversion on a machine with qemu-img available, such as the Linux/KVM build host.

Target	Path
VirtualBox (Windows/Linux x86-64)	Import the .ova (File → Import Appliance, enable EFI) or create an x86-64 Linux VM, attach the .vmdk and enable EFI.
VMware Workstation/Fusion (x86-64)	Import the .ova and configure UEFI firmware.
macOS Intel	Use a compatible x86-64 hypervisor with UEFI support and the appropriate disk format.
UTM (macOS Apple Silicon)	Can use .qcow2, but the available guest is x86-64 and must be emulated, not run as an ARM64 guest; expect substantially reduced performance.
VirtualBox/Parallels (Apple Silicon)	The existing x86-64 image is not supported for native ARM virtualization; an ARM64 guest build does not currently exist.
Windows ARM64	No supported or verified native guest image at present.

Limitations outside the Linux/KVM deployment:

• Data movement: 80-ingest and 90-extract depend on libvirt's QEMU guest-agent transport. They are not plug-and-play with alternative hypervisors. Replacing them with shared folders or SSH would change the security model and requires separate review.
• Display: Virtio video and display settings may need replacement with the selected hypervisor's devices and guest additions.
• Isolation: The documented host security boundary assumes KVM. Equivalent security assurances have not been verified for VirtualBox, VMware or UTM.
• Testing: The ability to boot an image does not mean the project has completed full integration, functionality or security testing on that host platform.

Operations

Run the numbered commands on the Linux host from the repository root unless stated otherwise.

Command	Function
00-build-lab-template.sh	Provision a template VM.
01-prepare-template-for-cloning.sh	Shut down, scrub instance identity and prepare a template for cloning.
02-create-vm-from-template.sh <name>	Clone a VM for a user or experiment.
10-upload-template-to-hf.sh	Seal and upload a candidate image, or resume an existing export with --existing dist/<image>.qcow2, including signed provenance.
11-release-template.sh	Promote a verified candidate with checksum and signed provenance; use --backfill <image>.qcow2 for already-public legacy releases.
12-export-image-vmdk.sh <image> [--ova]	Convert a sealed QCOW2 into VMDK, optionally OVA, for compatible alternative hypervisors.
20-import-lab-vm.sh <image> [name]	Import a downloaded QCOW2 image.
30-ensure-lab-tools.sh <vm>|all	Reconcile tools/configuration on an existing VM.
80-ingest-lab-data.sh <vm> <src> [batch]	Stage host data into the guest through the approved path.
90-extract-lab-data.sh <vm> [destination]	Pull staged exported artifacts from the guest.

Guest-side operational commands, including labloop-exec, labloop-export, labloop-build, and labloop-fault, retain their historical executable names for compatibility. They are components of GnosisLab-VM, not separate current products. Read the operational workflow and data-movement manual before using them.

Do not automatically open extracted archives on the host. Experiment output may be malicious or sensitive even when its checksum matches. Inspect it in an appropriate isolated environment.

MCP connectivity

The guest's agent clients connect to the GnosisLab services on the guest loopback interface. Current packaged defaults are:

Service	MCP endpoint	GUI
Agora	127.0.0.1:28050/mcp	28051
Arete	127.0.0.1:28060/mcp	28061
Zetesis	127.0.0.1:28070/mcp	28071
Episteme	127.0.0.1:28080/mcp	28081
Anamnesis	127.0.0.1:28090/mcp	28091

The execution/data-ingest interface may use additional ports. Ports are driven by the installed GnosisLab package's ports.env and can change; inspect the guest configuration instead of hardcoding them in new integrations.

For standalone installation, consult GnosisLab, its documentation, and the PyPI package.

Compatibility and migration

This project was previously called LabLoop or ML-LabLoop. Repository branding is now GnosisLab-VM, while the scientific runtime is GnosisLab. The historical labloop-* commands, LABLOOP_* settings, guest /srv/lab/... paths, and Hugging Face bucket names remain temporarily unchanged because they are operational interfaces or distribution locations. Do not rename them casually: preserve compatibility until migration procedures and tests exist.

Documentation and project policies

• Build, import and operational workflow
• Security policy and private vulnerability reporting
• Architecture, competitors and feature comparison
• Guest security model and operational rules
• Data movement and extraction
• Contributing
• Changelog
• Citation metadata
• Apache 2.0 license and third-party notices

Bug reports and feature proposals are welcome via GitHub issues. For vulnerabilities, follow SECURITY.md, not public issues.

Connect OpenCode to any host-local model

The VM driver can use any OpenAI-compatible inference API reachable over the libvirt NAT bridge (vLLM, SGLang, llama.cpp, LM Studio, or Ollama's OpenAI-compatible endpoint). The GnosisLab scientific services and experiment-zone network policy remain separate from the model endpoint. You do not need a Qwen-specific patch.

1. Start your inference server on the host. If it binds to 127.0.0.1:8002 (host-only), expose it only to the libvirt gateway with a relay:

   python3 scripts/host-llm-gateway.py --port 8002

   The relay listens on 192.168.122.1:8002, forwards to host 127.0.0.1:8002, and accepts only 192.168.122.0/24. It is a foreground process; stop with Ctrl+C. If your host vLLM is already listening at 192.168.122.1:8002 or 0.0.0.0:8002, do not start the relay on the same port. Restrict host firewall access to the VM bridge instead. Confirm the host actually has a running listener via ss -ltnp | grep ':8002' and curl -f http://127.0.0.1:8002/v1/models. If the host uses ufw, allow access only from the VM subnet on virbr0, for example sudo ufw allow in on virbr0 from 192.168.122.0/24 to 192.168.122.1 port 8002 proto tcp (review your policy first).

2. In the guest, check connectivity and register the served model IDs:

   curl --max-time 5 -f http://192.168.122.1:8002/v1/models
   python3 ~/Desktop/configure-host-models.py --url http://192.168.122.1:8002/v1 --context 262144

   This generates explicit OpenCode provider model entries from the server's real /v1/models IDs, so it works for Qwen3.6, Qwen3.8-Flash-Next, and unrelated models without hardcoding model names. The context flag should reflect your actual running server limit, and can be omitted. To use another server/port, change --url; to specify an ID on a non-discoverable API, use --model <served-id>. You can run the command again after switching models. The configurator preserves opencode.json (including GnosisLab MCP entries) and other JSON providers in opencode.jsonc. Restart OpenCode and choose the Host local models provider. Existing builds should copy deploy/configure-host-models.py to ~/Desktop/, or run ./30-ensure-lab-tools.sh <vm> on the host after updating.

Security: The model API is accessible to the driver VM and any other guest in the allowed libvirt subnet, not just GnosisLab. Do not expose a credential-free inference API to untrusted guests. For stronger multi-tenant isolation, configure authentication and host firewall restrictions. The relay never routes model traffic through the untrusted exp container.