import { VirtualShell, VirtualSshServer, SshClient } from "typescript-virtual-container";

const shell  = new VirtualShell("typescript-vm");
await shell.ensureInitialized();
shell.setPassword("root", "root");

const ssh = new VirtualSshServer({ port: 0, shell });
const port = await ssh.start();

const client = new SshClient();
await client.connect({ host: "localhost", port, username: "root", password: "root" });

await client.mkdir("/app/config", true);
await client.writeFile("/app/config/settings.json", JSON.stringify({ env: "dev" }));

const r = await client.exec("ls /app && cat /app/config/settings.json");
console.log(r.stdout);

Multi-VM, proxy, VPN, and hosting examples

See guides/EXAMPLES.md for:

• Baie — multi-VM network on a shared subnet
• VirtualProxy — port forwarding and SOCKS5 proxy
• Multi-tier lab — web/api/db with firewall isolation
• Hosting platform — multi-tenant with SSH per tenant
• VirtualVpn — encrypted tunnel between Baie instances
• Traffic shaping — latency, jitter (Gaussian), packet loss, burst loss, reordering, duplication
• Bandwidth enforcement — token bucket rate limiting per VM
• MTU enforcement — packets exceeding interface MTU are dropped
• Connection tracking — stateful conntrack with NEW/ESTABLISHED/TIME_WAIT states
• Advanced routing — multiple routing tables, policy-based routing, route metrics
• DNS, load balancer, partition

┌──────────────────────────────────────────────────────────────────────────┐
│  SshMimic (VirtualSshServer)             SftpMimic (VirtualSftpServer)  │
│  password auth · publickey auth          SFTP protocol handlers          │
│  per-IP rate limiting / lockout          home-dir confinement            │
└─────────────────────────┬────────────────────────────────────────────────┘
                          │
               ┌──────────▼──────────┐         ┌──────────────────────────┐
               │    VirtualShell     │────────▶ │    DesktopManager        │
               │  script parser      │          │  XFCE panel · windows    │
               │  command executor   │          │  Thunar · Mousepad       │
               │  .bashrc loader     │          │  Trash · terminal windows│
               │  session manager    │          │  (browser only)          │
               └──┬──────────────┬───┘          └──────────────────────────┘
                  │              │
     ┌────────────▼───┐    ┌─────▼───────────────┐
     │VirtualFileSystem│   │ VirtualUserManager   │
     │ in-memory tree  │   │ scrypt · sudoers     │
     │ gzip · symlinks │   │ publickey auth       │
     │ .vfsb binary    │   │ quotas · sessions    │
     │ mode:memory|fs  │   └─────────────────────-┘
     └─────────────────┘
                  │
     ┌────────────▼────────────┐
     │   VirtualNetworkManager │
     │ interfaces · routes     │
     │ firewall · ARP          │
     │ conntrack · policy rules│
     │ multi-table routing     │
     └─────────────────────────┘
                  │
     ┌────────────▼────────────┐
     │        HoneyPot         │
     │ audit log · stats       │
     │ anomaly detection       │
     └─────────────────────────┘

What it is: a shell emulator and virtual Linux environment for developer workflows.

What it is not: a fully isolated sandbox. The shell commands are contained — no host binary is ever spawned, execvp is never called, node/python3/npm are virtual stubs. Permission enforcement follows POSIX semantics (owner/group/other, sticky bit, setuid) for all file operations, and unknown users are auto-provisioned with non-root UIDs. But curl/wget use the real fetch() API (live network access), all instances share the same JS heap as the host application, and resource capping is enforced at the VFS/process level (not at the kernel level). Do not expose to untrusted input without additional infrastructure-level isolation.

Two execution modes for different isolation needs:

import { VirtualShell, SandboxedShell } from "typescript-virtual-container";

// Shared heap — lightweight, full-featured
const shell = new VirtualShell("dev-vm");
await shell.ensureInitialized();
const r1 = await shell.exec("echo hello");
console.log(r1.stdout); // "hello\n"

// Isolated worker — separate heap, exec-only
const sandbox = new SandboxedShell({ execTimeoutMs: 10_000 });
const r2 = await sandbox.exec("echo hello", "root", "/root");
console.log(r2.stdout); // "hello\n"
sandbox.terminate();

Limit the RAM and CPU resources visible inside a virtual shell. Pass a VirtualShellResourceCaps object as the 4th constructor argument:

import { VirtualShell } from "typescript-virtual-container";

const shell = new VirtualShell("prod-vm", undefined, undefined, {
  ramCapBytes: 2 * 1024 * 1024 * 1024, // 2 GiB VFS storage limit
  cpuCapCores: 2,                        // 2 vCPUs
});

Reporting (always active)

When a cap is set, every /proc file, sysctl entry, cgroup file, and system-monitor command reports the capped value instead of the real host total:

RAM enforcement

When ramCapBytes is set, the VFS tracks total bytes stored in its in-memory tree. Any write that would cause the total to exceed the cap is rejected with an ENOMEM error:

$ dd if=/dev/zero of=/tmp/big bs=1M count=3000
ENOMEM: Cannot allocate memory: write to '/tmp/big' would exceed RAM cap

This covers all VFS writes: echo > file, dd, cp, tee, SFTP uploads, etc. Compressed files count their compressed size.

Note: this caps VFS storage, not Node.js heap usage. A process that allocates large JS objects without writing to the VFS will not be blocked.

CPU enforcement

When cpuCapCores is set, a background watcher tracks wall-clock time per process. If a process exceeds the per-window budget (cpuCapCores × 1000 ms per second), it is killed with SIGKILL (exit code 137):

$ while true; do :; done
Killed  # exit code 137

Short commands (ls, echo, cat) are unaffected. The process:killed:cpu event is emitted with { pid, command, cpuTime }.

Process scheduler

The VFS includes a priority-based process scheduler inspired by Linux CFS. When enabled, processes receive CPU time proportional to their nice value (-20 = highest priority, 19 = lowest):

shell.users.enableScheduler({
  baseTimesliceMs: 100,
  maxTimesliceMs: 500,
  enforceFairShare: true,
});

shell.users.setProcessNice(1234, -10); // boost priority
shell.users.getSchedulerStats();       // { scheduleCount, throttleCount, ... }

In the shell:

nice -n -10 my-command    # run with high priority
nice -n 15 -p 1234        # lower priority of running process
ps aux                    # shows NI (nice) and PRI columns

The scheduler tracks per-process CPU time in accounting windows and throttles processes that consume more than 2× their fair share, preventing any single process from monopolizing the CPU.

Runtime changes

Both caps can be changed at runtime via sysctl:

sysctl vm.ram_cap_bytes=1073741824   # 1 GiB
sysctl kernel.cpu_cap_cores=2         # 2 vCPUs
sysctl vm.ram_cap_bytes=0             # remove RAM cap

When running in "fs" persistence mode with swapEnabled: true, the VFS can offload evicted file contents to individual swap files on disk. This provides two benefits:

1. O(1) reload — reading an evicted file loads from its swap file directly, instead of parsing the entire snapshot.
2. RAM overflow handling — when a write would exceed ramCapBytes, the VFS swaps out the least recently used (LRU) files to make room instead of immediately rejecting with ENOMEM.

import { VirtualFileSystem } from "typescript-virtual-container";

const vfs = new VirtualFileSystem({
  mode: "fs",
  snapshotPath: "./data",
  swapEnabled: true,         // enable swap store
  swapDir: "./data/swap",    // optional: custom swap directory (defaults to <snapshotPath>/swap)
});

How it works

• When a file is evicted (by evictLargeFiles(), evictUnusedLargeFiles(), or RAM cap pressure), its content is written to <swapDir>/<hash>.swap with a small binary header.
• The in-memory node keeps evicted: true and content = Buffer.alloc(0).
• On the next readFile(), the content is loaded from the swap file and the swap entry is deleted.
• Swap is disabled by default — it must be explicitly enabled via VfsOptions.

Swap command

$ swap -s              # show swap statistics
Swap usage:
  Files swapped out : 12
  Swap disk usage   : 4.2 MB
  Original size     : 3.8 MB
  Swap-in ops       : 45
  Swap-out ops      : 57

$ swap -c              # clear all swap files
swap: swap files cleared

The apt/dpkg/pacman commands are fully virtual — they do not install real system packages. Instead, they manage a curated database of ~25 virtual packages that write files into the VFS and register new shell commands.

What apt install actually does

1. Looks up the package in the internal database (VirtualPackageManager)
2. Writes the package's files into the VFS (e.g. /usr/bin/python3.12, /usr/lib/...)
3. Registers any bundled commands in the shell's command registry
4. Records the installation in /var/lib/dpkg/status

Available packages

Important: These are not real packages. Installing python3 does not give you a full Python interpreter — it provides a virtual REPL stub that simulates basic Python behavior. The same applies to all other packages. This is intentional: the project is designed to be a self-contained virtual environment, not a real package manager.

Package-gated commands

Some commands require apt install before they become available:

$ gcc --version
Command 'gcc' not found

$ apt install gcc
$ gcc --version
gcc (Fortune 13.3.0-nyx1) 13.3.0

API reference for all core classes and utilities. Designed for quick lookup while developing with the library. More extensive documentation, examples, and guides are available in the documentation.

All examples are available as runnable TypeScript files in the examples/ directory:

Type help in the shell for a grouped, colorized listing. Type help <command> for detailed usage. Type man <command> for full manual pages — all commands are documented.

Navigation

Files

Text

Archives

System

Network

Session

User & Group Management

Package

Shell

Desktop (browser only)

Desktop commands are no-ops outside the browser environment.

Fun

ℹ️ All 223 built-in commands include complete JSDoc documentation with @category and @params tags. See src/commands/ for source code and inline documentation.

Custom commands: shell.addCommand(name, params, callback).

The interpreter supports a POSIX sh subset via sh -c '...', sh <file>, or interactive session.

Operators and Redirections

mkdir /app && echo "created"     # && — only if previous succeeds
rm /missing || echo "not found"  # || — only if previous fails
echo a; echo b; echo c           # ; — always all three

cat /etc/hosts | grep local
echo "hello" > /tmp/out.txt      # overwrite
cat /tmp/out.txt >> /tmp/log.txt # append

Variable Expansion

export NAME=world
echo "Hello $NAME"            # basic variable
echo "${NAME:-fallback}"      # default if unset
echo "$(whoami)"              # command substitution
echo $((2 + 3))               # arithmetic expansion
echo "${HOME}"                # curly brace delimited

Arithmetic

echo $((2 + 3))        # 5
X=4; echo $((X * 2))   # 8
i=0; i=$((i + 1))      # increment

Conditionals

if [ -f /etc/config ]; then
  echo "config exists"
elif [ -d /etc ]; then
  echo "etc is a directory"
else
  echo "nothing found"
fi

[ "$USER" = "root" ] && echo "root"
[ $COUNT -gt 10 ] && echo "large"

Loops

for name in alice bob charlie; do
  echo "Hello $name"
done

COUNT=0
while [ $COUNT -lt 3 ]; do
  echo "Count: $COUNT"
  COUNT=$((COUNT + 1))
done

until [ $COUNT -eq 0 ]; do
  echo "Countdown: $COUNT"
  COUNT=$((COUNT - 1))
done

Functions and case

greet() {
  echo "Hello, $1!"
}
greet world

case "$1" in
  start) echo "Starting..." ;;
  stop)  echo "Stopping..." ;;
  *)     echo "Usage: $0 {start|stop}" ;;
esac

Heredoc

cat << EOF
line one
line two
EOF

# write to file
cat > /tmp/config << EOF
HOST=localhost
PORT=3000
EOF

set -e / set -x

set -e          # exit immediately on any non-zero exit code
set -x          # print each command before executing (trace)
set +e          # disable errexit
set +x          # disable xtrace

Script Files

shell.vfs.writeFile("/usr/local/bin/setup.sh", `
#!/bin/sh
for dir in config logs tmp; do
  mkdir /app/$dir
done
`);
await client.exec("sh /usr/local/bin/setup.sh");

Login Files

Sourced automatically at session start, in order:

1. /etc/environment — KEY=VALUE pairs only, no shell syntax
2. ~/.profile — user login script
3. ~/.bashrc — interactive shell config

export EDITOR=nano
alias ll="ls -l"
echo "Welcome, $USER!"

Set .bashrc programmatically:

shell.vfs.writeFile("/home/root/.bashrc", `
export EDITOR=nano
alias ll="ls -l"
echo "Welcome back, root!"
`.trim());

Directory Layout

On every VirtualShell init, a realistic Linux hierarchy is bootstrapped idempotently:

/
├── bin/
│   ├── [47 stubs: sh, bash, python3, ...]
├── boot/
├── dev/
│   ├── null, zero, random, urandom, tty, ...
├── etc/
│   ├── passwd, shadow, group, sudoers, hostname, ...
├── home/
│   └── root/
├── opt/
├── proc/
│   ├── (dynamic — uptime, meminfo, cpuinfo, stat, ...)
├── root/
├── run/
├── sbin/
│   └── init
├── sys/
├── tmp/
├── usr/
│   ├── bin/
│   ├── lib/python3.12/
│   ├── share/
│   └── src/
└── var/
    ├── log/
    └── lib/apt/

shell.refreshProcFs();   // refresh /proc/* with current system state
shell.syncPasswd();      // sync /etc/passwd|group|shadow from user manager

VFS PATH Resolution

When a command is not a built-in, the shell searches $PATH in the VFS — binaries installed by apt become immediately accessible.

• /sbin and /usr/sbin are excluded from $PATH for non-root users.
• Stubs containing exec builtin <name> delegate to the named built-in TS command.

Package-gated commands (require apt install):

Built-in Package Registry (25 packages)

Environment Variables

Constructor Options

new VirtualShell(hostname, properties?, vfsOptions?)
// vfsOptions: { mode: "memory"|"fs", snapshotPath?: string }

new VirtualSshServer({
  port, hostname?,
  shell?,
  maxAuthAttempts?,   // default: 5
  lockoutDurationMs?, // default: 60_000
})

new VirtualSftpServer({ port, hostname?, shell? })
// or: { port, vfs, users } without a shell instance

bun ./benchmark-virtualshell.ts

Reports shell initialization time, command execution time, and RSS memory by concurrency. Designed to scale to 1000+ parallel environments.

• SSH server is event-driven — handles many concurrent connections.
• SshClient is sequential per instance — create multiple for parallel operations.
• Each VirtualShell is fully independent.

Tips:

• Use SSH_MIMIC_FAST_PASSWORD_HASH=1 in tests to skip scrypt overhead.
• Reuse long-lived shell instances for low-latency command bursts.

Each VirtualShell holds its VFS tree, process table, sessions, and file descriptors entirely in the JS heap. For long-running servers or multi-shell deployments, two mechanisms keep memory in check:

Idle freeze/thaw

After a configurable period of inactivity, the VFS tree is serialised to a compact binary buffer and the live object graph is released. On the next command the tree is reconstructed in ~0.1 ms.

await shell.ensureInitialized();
shell.enableIdleManagement({
  idleThresholdMs: 60_000,   // freeze after 60s of inactivity
  checkIntervalMs: 15_000,   // check every 15s
});
// Events: shell.on("shell:freeze", ...) / shell.on("shell:thaw", ...)

Garbage collector

The GC is built into IdleManager and runs automatically when idle management is enabled. Each cycle (default every 30s) performs four steps in order:

1. Scan process table — find all processes with status === "done" and remove them.
2. Clean stale CPU entries — remove CPU time tracking for PIDs that no longer exist.
3. Evict closed large files — walk the VFS tree and zero out file contents that exceed the eviction threshold and have no open file descriptors. Evicted files are reloaded on demand from the snapshot.
4. Trigger Node.js GC — if the runtime was started with --expose-gc, call globalThis.gc() to force V8 to reclaim memory immediately.

shell.enableIdleManagement({
  idleThresholdMs: 60_000,
  gcIntervalMs: 30_000,  // GC runs every 30s (0 = disabled)
});

The GC timer is unref()'d so it never blocks process.exit().

Manual trigger and stats:

const idle = new IdleManager(shell);
const stats = idle.runGc();
// stats: {
//   terminatedProcesses: 3,   // process records removed this cycle
//   staleCpuEntries: 1,       // orphaned CPU time entries cleared
//   evictedFiles: 2,          // large files zeroed out (no open FDs)
//   forcedGc: false,          // true only when --expose-gc is passed to Node/Bun
// }

idle.on("gc:run", (stats) => console.log(stats));

Note: In "fs" mode the existing evictionThresholdBytes option (default 64 KB) already evicts large files after each flushMirror(). The GC extends this by also checking open file descriptor state — a large file that is currently open by a running command will NOT be evicted, even if it exceeds the threshold.

import type {
  VfsOptions, VfsPersistenceMode,
  VfsSnapshot, VfsNodeStats, VfsFileNode, VfsDirectoryNode,
  WriteFileOptions, RemoveOptions,
  CommandContext, CommandResult, CommandMode, CommandOutcome,
  ShellModule, ShellEnv, SudoChallenge, NanoEditorSession,
  AuditLogEntry, HoneyPotStats,
  ShellStream, ExecStream,
} from "typescript-virtual-container";

Error: listen EADDRINUSE :::2222 — port already in use. Change port or stop existing process.

Auth always fails — root has no password by default. Verify with users.verifyPassword(username, password). Check lockout: ssh.clearLockout(ip).

Command 'xyz' not found (exit 127) — not a registered built-in and not found in VFS $PATH. Register with shell.addCommand() or apt install the package.

Shell scripting — if block not working — ensure each keyword is on its own line or separated by ;.

snapshotPath required error — set mode: "fs" without snapshotPath: new VirtualFileSystem({ mode: "fs", snapshotPath: "./data" }).

Variables not persisting between exec() calls — SshClient shares one ShellEnv per shell instance. export in one call is visible in the next. For isolation, create a new SshClient.

Too many levels of symbolic links — symlink chain exceeds 8 hops. Check for circular links or increase maxDepth in resolveSymlink().

What exactly is this project? A self-contained Linux environment implemented entirely in TypeScript. It is not a mock, a stub, or a thin SSH wrapper — it is a full virtual container with its own filesystem (VirtualFileSystem), user and permission system (VirtualUserManager), shell interpreter, package manager, network layer, process table, and desktop environment. Each VirtualShell instance is an independent container that runs anywhere TypeScript runs: Node.js, Bun, or the browser.

How is this different from a Docker container or a real VM? Docker and VMs enforce kernel-level isolation and run real binaries. This project runs entirely in the JavaScript runtime — no subprocess is ever spawned, no host binary is called. The trade-off is intentional: you get zero-dependency portability (including the browser), a fully inspectable and programmable environment, and no host OS requirements. It is not a security boundary.

Is the environment fully isolated? No — and this is important to understand before exposing it to untrusted input:

• Network is real. curl and wget use the host's fetch() — requests reach the actual internet.
• The JS heap is shared. All VirtualShell instances run in the same JavaScript runtime as your application. There is no memory boundary between them or between the shell and the host.
• No resource enforcement. CPU usage and memory consumption are not capped by the container itself — a runaway loop consumes real host resources.
• Filesystem isolation holds in "memory" mode (the VFS never touches the host FS) and is limited to one .vfsb file in "fs" mode.

In short: the shell commands are sandboxed, the runtime is not.

Can I use this in production? Yes, for the right use cases: automated test harnesses, interactive tutorials, training environments, honeypots, and browser-based shell experiences. Do not expose it to arbitrary untrusted input without additional isolation at the infrastructure level — it is not a security boundary.

Does the VFS touch the host filesystem? In "memory" mode: never. In "fs" mode: exactly one binary file (vfs-snapshot.vfsb) inside snapshotPath. In the browser: IndexedDB only.

Can I run multiple isolated environments in parallel? Yes. Each new VirtualShell(...) is fully independent — separate VFS, user database, environment state, and session manager. They share no global state.

Does the shell support &&, ||, ;, and &? Yes — plus pipes, redirections, if/for/while/until/case, function definitions, arrays, brace expansion, glob expansion, heredocs, set -e/set -x, and background jobs (cmd &).

Can I use this for honeypot deployments? Yes — HoneyPot.attach() captures every command, file write, auth attempt, and session event with timestamps. Configure maxAuthAttempts to throttle scanners. Export the audit log on shutdown.

Is SFTP fully supported? Core operations are implemented. Extended attributes and symlinks return OP_UNSUPPORTED.

Does the desktop work outside the browser? No — startxfce4, thunar, and mousepad require a DOM. In Node.js/Bun they return an error immediately. The DesktopManager is only instantiated in the web shell example (demo/app.ts).

What does the desktop simulate? A single-user XFCE session: a panel with Applications menu and clock, draggable windows, a file manager (Thunar) with navigation, right-click context menu, rename, and trash, a text editor (Mousepad) with Ctrl+S save, and terminal windows each backed by a real interactive shell session against the same VFS.

1. Fork and create a feature branch: git checkout -b feat/my-feature
2. Add changes and tests.
3. Format and lint: bun format && bun check
4. Push and open a PR.

Standards: Biome formatting · full TypeScript (no any) · ✅ JSDoc on all built-in commands · async/await · description and category fields on new ShellModule · unit tests (prioritized for core features; advanced tests planned).

• Passwords hashed with scrypt (N=32768, r=8, p=1) with random per-user salt.
• Root account always exists and cannot be deleted.
• Per-IP rate limiting prevents automated brute-force on the SSH server.
• Account lockout — accounts are locked after 5 consecutive failed login attempts.
• Password aging — configurable min/max age, warning period, and account expiry via chage.
• Account lock/unlock — password hash prefixed with ! to disable authentication.
• Sudo timestamp caching — 5-minute credential cache matching real sudo behavior.
• Group-based permissions — supplementary groups tracked in /etc/group with full membership management.
• This project does not provide kernel-level or process-level isolation. All VirtualShell instances share the same JS heap as the host application.
• curl and wget issue real network requests via fetch() — they are not sandboxed.
• Do not expose to untrusted input without additional infrastructure-level isolation.

Vulnerability reports: contact maintainers privately before public disclosure — see SECURITY.md.

• Node.js: >=18 · Bun: Supported · TypeScript: >=5.0
• OS: Linux, macOS, Windows (via Node/Bun)