vce-shell 0.1.1

VCE Shell layer: command language, builtins, execution coordination
Documentation

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.

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:

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:

cargo install vce

Or build the workspace from source:

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.

# Cargo.toml
[dependencies]
vce = "0.1"
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 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.