# 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.
```console
$ 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.
| 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](https://github.com/chrisreyer/vce/releases/latest). Each
archive contains the `vce` executable, README, and licenses; `SHA256SUMS`
on the release verifies the downloads. Rust is not required.
```sh
vce --os linux --shell bash --user demo
vce --os macos --shell zsh --user demo
vce --os windows --shell powershell --user demo
```
Pipe commands in for scripted machines—VCE switches to line mode
automatically:
```sh
printf 'id\nls /etc\nsudo -S cat /etc/shadow\ndemo\n' \
| vce --os linux --user demo
```
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:
```sh
cargo install vce
```
Or build the workspace from source:
```sh
cargo build -p vce --release
```
## 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.
```toml
# Cargo.toml
[dependencies]
vce = "0.1"
```
```rust
use vce::{FileMode, Machine, OsKind, ShellChoice};
fn main() -> Result<(), vce::MachineError> {
let machine = Machine::builder(OsKind::Linux)
.username("demo")
.hostname("lab-host")
.build()?;
machine.configuration().write_file(
"/etc/lab.conf",
b"ready=yes\n",
FileMode::FILE_644,
)?;
let mut session = machine.session(Some(ShellChoice::Bash))?;
let result = session.execute("cat /etc/lab.conf")?;
assert_eq!(result.stdout_text(), "ready=yes\n");
Ok(())
}
```
See [Embedding VCE](docs/API.md) for construction, configuration, sessions,
state inspection, events, and virtual time.
## Architecture
```text
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](CONTRIBUTING.md).
## License
Dual-licensed under [Apache 2.0](LICENSE-APACHE) and [MIT](LICENSE-MIT).