VCE
A stateful OS simulator. No VM, no container, no kernel.
VCE boots a Linux, macOS, or Windows machine and lets you operate it through its normal shell. Commands parse arguments, check permissions, read state, write state, and leave consequences for the next command to find.
$ vce --os linux --user demo
sudo ufw enable
[sudo] password for demo:
Firewall is active and enabled on system startup
ufw status
Status: active
cat /etc/ufw/ufw.conf
ENABLED=yes
...
sudo ufw deny 22/tcp
Rule added
Rule added (v6)
sudo cat /etc/ufw/user.rules
[sudo] password for demo:
...
### tuple ### deny tcp 22 0.0.0.0/0 any 0.0.0.0/0 in
...
ufw enable writes /etc/ufw/ufw.conf. ufw status reads it. cat reads
the same bytes. There is no separate “firewall enabled” flag that only ufw
can see. The file is the state.
That is the governing rule across the system.
What makes VCE different
Most OS simulators fake command output. VCE models the observable contract of the OS: the authoritative files, registry keys, and kernel-owned namespaces that make a machine a machine.
| How state works | |
|---|---|
| Mocked CLI | Each command returns a prepared string |
| Container / VM | Real OS, real kernel, real overhead |
| VCE | Commands read and write the same authoritative locations a real OS uses |
The result is convergence: commands cannot disagree when they share one source
of truth. Enable a systemd service and its wants symlink is created where
systemctl status looks for it. Remove that symlink directly and systemctl
notices. Change a service registry key with reg and sc sees it.
VCE is an engine, not an application. Think of what Unity is to games: you build on top of it. A shell exercise tool, a cyber-range platform, a CLI agent harness, or a sysadmin course backend—these are things you build with VCE, not things VCE is.
Getting started
Download the latest build for your platform from the
releases page. Each
archive contains the vce executable, README, and licenses; SHA256SUMS
on the release verifies the downloads. Rust is not required.
Pipe commands in for scripted machines—VCE switches to line mode automatically:
|
Each run starts from a fresh machine. VCE never reads or touches your host OS.
With Rust 1.97 or newer, the same binary can be installed from crates.io:
Or build the workspace from source:
What’s implemented
Three OS profiles, four shells, and a surface that grows command by command.
Linux
Ubuntu 24.04 on x86_64, with apt, dpkg, systemctl, ufw, useradd,
getent, GNU stat, ip, ifconfig, and more. dpkg state lives in
/var/lib/dpkg; systemd has unit files, runtime state, and wants symlinks; UFW
has configuration and rule files; the machine includes account files, APT
sources, login records, and an audit log.
macOS
Modern macOS on arm64 with Zsh by default, plus brew, open, launchctl,
defaults, dscl, fdesetup, socketfilterfw, and more. Homebrew uses its
Cellar and Caskroom under /opt/homebrew; preferences are plists; applications
are .app bundles in /Applications; launch daemons are plist state.
Windows
Windows 10 Pro with PowerShell by default, plus sc, net, netsh, reg,
wmic, secedit, tasklist, and more. SYSTEM, SOFTWARE, SAM, SECURITY, and
DEFAULT live at their hive locations; services, shares, firewall, and policy
are registry state.
Shells
Bash, Zsh, PowerShell, and cmd each have their own language conventions, builtins, prompt, history, and command resolution. They are not skins over a shared parser.
Shared Unix surface
ls, cat, cp, mv, rm, mkdir, chmod, chown, sudo, su, ps,
kill, grep, sed, find, vim, nano, top, man, and more.
Using VCE as a library
The vce crate is the supported application boundary. Your application can
construct and retain a machine, configure its actual OS state, open persistent
user or administrative sessions, capture command results, inspect the Engine,
and synchronously observe changes. Scenario generation remains the embedding
application's concern.
# Cargo.toml
[]
= "0.1"
use ;
See Embedding VCE for construction, configuration, sessions, state inspection, events, and virtual time.
Architecture
host stdin / keyboard
│
▼
┌───────────────┐
│ vce │ boot, login, session, host adapter
└───────┬───────┘
▼
┌───────────────┐
│ shell │ Bash, Zsh, PowerShell, cmd
└───────┬───────┘
▼
┌───────────────┐
│ os │ layouts, identity, commands, runtime
└───────┬───────┘
▼
┌───────────────┐
│ engine │ objects, authorization, events, time, I/O
└───────────────┘
Dependencies point downward. The Engine has no concept of Linux, Homebrew, or
a firewall. It owns generic objects, an authorization policy, a virtual clock,
and an event bus. The OS layer gives those objects meaning. Shells coordinate
language and execution. The terminal crate implements the Engine’s terminal
interface, and vce composes everything into a library and binary.
Project status
VCE is an early public project. Its implemented surface is tested and intended to be internally coherent, but it does not cover every command on any supported OS. If something is not implemented, VCE says so rather than fabricating output.
Contributions are welcome. See CONTRIBUTING.md.
License
Dual-licensed under Apache 2.0 and MIT.