v1.4.1

assets/base-images/smartvm-minimal.manifest.example.json

@@ -0,0 +1,22 @@
+{
+  "schemaVersion": 1,
+  "bundleId": "smartvm-minimal-v1-x86_64",
+  "name": "SmartVM minimal x86_64 bundle",
+  "arch": "x86_64",
+  "firecrackerVersion": "v1.15.1",
+  "rootfsType": "ext4",
+  "rootfsIsReadOnly": false,
+  "bootArgs": "console=ttyS0 reboot=k panic=1 pci=off",
+  "kernel": {
+    "url": "https://assets.example.com/push.rocks/smartvm/base-images/smartvm-minimal-v1/x86_64/vmlinux",
+    "fileName": "vmlinux",
+    "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+    "sizeBytes": 12345678
+  },
+  "rootfs": {
+    "url": "https://assets.example.com/push.rocks/smartvm/base-images/smartvm-minimal-v1/x86_64/rootfs.ext4",
+    "fileName": "rootfs.ext4",
+    "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+    "sizeBytes": 12345678
+  }
+}

changelog.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 2026-05-01 - 1.4.1 - fix(readme)
+improve documentation for Firecracker runtime, networking, and base image usage
+
+- expand the project overview and feature summary with clearer runtime, networking, firewall, and WireGuard behavior
+- clarify host requirements, root privilege expectations, and optional tooling for blank rootfs creation
+- add quick-start outcome details and stronger guidance for using hosted base image manifests in production
+
+## 2026-05-01 - 1.4.0 - feat(network)
+add configurable VM egress firewall policies and WireGuard-based host routing
+
+- adds firewall and wireguard options to SmartVM and NetworkManager configuration interfaces
+- validates firewall rules, WireGuard managed configs, and unsupported hook or IPv6 settings with dedicated error codes
+- sets up iptables egress chains, NAT, policy routing, and cleanup for managed VM subnet traffic
+- documents the new networking capabilities and adds tests for config validation and option forwarding
+
+## 2026-05-01 - 1.3.1 - fix(docs)
+remove outdated base image bundle readme and consolidate hosted manifest documentation
+
+- Deletes the dedicated assets/base-images/readme.md documentation file
+- Keeps hosted base image manifest guidance and example usage in the main project README
+
+## 2026-05-01 - 1.3.0 - feat(runtime)
+stage VM runtime artifacts and writable drives in per-VM ephemeral storage by default
+
+- default runtime files to /dev/shm/.smartvm/runtime when available, with per-VM socket and drive staging paths
+- copy writable drives into per-VM runtime storage before boot and remove them during cleanup, with per-drive and global opt-out controls
+- prefer squashfs rootfs images over ext4 when resolving Firecracker CI base images
+- add tests and documentation for ephemeral drive staging and runtime directory defaults
+
+## 2026-05-01 - 1.2.0 - feat(base-images)
+add managed base image bundles with cache retention, hosted manifests, and opt-in integration boot testing
+
+- introduces BaseImageManager with support for Firecracker CI presets and hosted manifest-based kernel/rootfs bundles
+- adds SmartVM.ensureBaseImage() and exports new base image types and manager APIs
+- validates and verifies downloaded base image artifacts with checksums and bounded cache eviction
+- hardens process, socket, network, and config handling with safer spawning, subnet/interface validation, and expanded tests
+
 ## 2026-04-30 - 1.1.1 - fix(build)
 tighten TypeScript compiler settings and harden error message handling
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartvm",
-  "version": "1.1.1",
+  "version": "1.4.1",
   "private": false,
   "description": "A TypeScript module wrapping Amazon Firecracker VMM for managing lightweight microVMs",
   "type": "module",

readme.hints.md

@@ -5,6 +5,11 @@
 - Uses `@push.rocks/smartrequest` with URL format `http://unix:<socket>:<path>` for socket communication
 - Uses `@push.rocks/smartshell` `execStreaming()` to manage Firecracker child processes
 - Uses `@push.rocks/smartexit` for cleanup on process exit
+- `BaseImageManager` downloads Firecracker CI demo artifacts or hosted project manifests into `/tmp/.smartvm/base-images` by default
+- Base image cache keeps 2 bundles by default and warns before evicting older bundles
+- Hosted manifest examples live in `assets/base-images/`
+- VM runtime files default to `/dev/shm/.smartvm/runtime` when available
+- Writable drives are staged into per-VM runtime storage by default and removed during cleanup; use `ephemeral: false` only for explicit persistence
 
 ## Key API Patterns
 - SmartRequest: `SmartRequest.create().url(...).json(body).put()` — response has `.status`, `.ok`, `.json()`
@@ -16,3 +21,9 @@
 - Start: PUT /actions { action_type: "InstanceStart" }
 - Pause/Resume: PATCH /vm { state: "Paused" | "Resumed" }
 - Stop: PUT /actions { action_type: "SendCtrlAltDel" }
+
+## Integration Testing
+- Default `pnpm test` skips real Firecracker boot testing
+- Set `SMARTVM_RUN_INTEGRATION=true` to run the opt-in boot test
+- `SMARTVM_BASE_IMAGE_PRESET` supports `latest` and `lts`; default is `latest`
+- Hosted/project-owned bundles use `baseImageManifestUrl`, `baseImageManifestPath`, `manifestUrl`, or `manifestPath`

test/test.integration.node.ts

@@ -0,0 +1,91 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+import { BaseImageManager, SmartVM } from '../ts/index.js';
+import type { TBaseImagePreset, TFirecrackerArch } from '../ts/index.js';
+
+const integrationEnabled = ['1', 'true', 'yes'].includes(
+  (process.env.SMARTVM_RUN_INTEGRATION || '').toLowerCase(),
+);
+
+function getHostArch(): TFirecrackerArch {
+  return process.arch === 'arm64' ? 'aarch64' : 'x86_64';
+}
+
+async function assertHostReady(): Promise<void> {
+  if (process.platform !== 'linux') {
+    throw new Error('Firecracker integration tests require Linux');
+  }
+  await fs.promises.access('/dev/kvm', fs.constants.R_OK | fs.constants.W_OK);
+}
+
+tap.test('SmartVM integration - boots a Firecracker CI base image when explicitly enabled', async () => {
+  if (!integrationEnabled) {
+    console.log('Skipping SmartVM integration test. Set SMARTVM_RUN_INTEGRATION=true to enable it.');
+    return;
+  }
+
+  await assertHostReady();
+
+  const arch = (process.env.SMARTVM_ARCH as TFirecrackerArch | undefined) || getHostArch();
+  const preset = (process.env.SMARTVM_BASE_IMAGE_PRESET as TBaseImagePreset | undefined) || 'latest';
+  const maxStoredBaseImages = process.env.SMARTVM_MAX_STORED_BASE_IMAGES
+    ? Number(process.env.SMARTVM_MAX_STORED_BASE_IMAGES)
+    : undefined;
+  const baseImageManager = new BaseImageManager({
+    arch,
+    cacheDir: process.env.SMARTVM_BASE_IMAGE_CACHE_DIR,
+    maxStoredBaseImages,
+    hostedManifestUrl: process.env.SMARTVM_BASE_IMAGE_MANIFEST_URL,
+    hostedManifestPath: process.env.SMARTVM_BASE_IMAGE_MANIFEST_PATH,
+  });
+  const baseImage = await baseImageManager.ensureBaseImage({
+    preset,
+    manifestUrl: process.env.SMARTVM_BASE_IMAGE_MANIFEST_URL,
+    manifestPath: process.env.SMARTVM_BASE_IMAGE_MANIFEST_PATH,
+  });
+
+  const smartvm = new SmartVM({
+    arch,
+    dataDir: process.env.SMARTVM_INTEGRATION_DATA_DIR || path.join(os.tmpdir(), '.smartvm-integration'),
+    firecrackerVersion: process.env.SMARTVM_FIRECRACKER_VERSION || baseImage.firecrackerVersion,
+    baseImageCacheDir: process.env.SMARTVM_BASE_IMAGE_CACHE_DIR,
+    maxStoredBaseImages,
+    baseImageManifestUrl: process.env.SMARTVM_BASE_IMAGE_MANIFEST_URL,
+    baseImageManifestPath: process.env.SMARTVM_BASE_IMAGE_MANIFEST_PATH,
+  });
+  const vm = await smartvm.createVM({
+    id: `smartvm-it-${Date.now()}`,
+    bootSource: {
+      kernelImagePath: baseImage.kernelImagePath,
+      bootArgs: baseImage.bootArgs,
+    },
+    machineConfig: {
+      vcpuCount: 1,
+      memSizeMib: 256,
+    },
+    drives: [
+      {
+        driveId: 'rootfs',
+        pathOnHost: baseImage.rootfsPath,
+        isRootDevice: true,
+        isReadOnly: baseImage.rootfsIsReadOnly,
+      },
+    ],
+  });
+
+  try {
+    await vm.start();
+    expect(vm.state).toEqual('running');
+    expect(await vm.getInfo()).toBeTruthy();
+  } finally {
+    if (vm.state === 'running' || vm.state === 'paused') {
+      await vm.stop();
+    }
+    await vm.cleanup();
+    await smartvm.cleanup();
+  }
+});
+
+export default tap.start();

test/test.ts

@@ -1,11 +1,40 @@
+import * as fs from 'fs';
+import * as crypto from 'crypto';
+import * as os from 'os';
+import * as path from 'path';
 import { tap, expect } from '@git.zone/tstest/tapbundle';
 import {
+  BaseImageManager,
   VMConfig,
   SocketClient,
   NetworkManager,
+  MicroVM,
   SmartVM,
+  SmartVMError,
 } from '../ts/index.js';
-import type { IMicroVMConfig } from '../ts/index.js';
+import type { IBaseImageBundle, IBaseImageHostedManifest, IMicroVMConfig } from '../ts/index.js';
+
+async function getRejectedError(promise: Promise<unknown>): Promise<unknown> {
+  try {
+    await promise;
+  } catch (err) {
+    return err;
+  }
+  return undefined;
+}
+
+function getThrownError(fn: () => unknown): unknown {
+  try {
+    fn();
+  } catch (err) {
+    return err;
+  }
+  return undefined;
+}
+
+function sha256Buffer(buffer: Buffer): string {
+  return crypto.createHash('sha256').update(buffer).digest('hex');
+}
 
 // ============================================================
 // VMConfig Tests
@@ -87,6 +116,33 @@ tap.test('VMConfig - validate() should fail for multiple root drives', async ()
   expect(result.valid).toBeFalse();
 });
 
+tap.test('VMConfig - validate() should fail for invalid vsock guestCid', async () => {
+  const vmConfig = new VMConfig({
+    bootSource: { kernelImagePath: '/vmlinux' },
+    machineConfig: { vcpuCount: 1, memSizeMib: 128 },
+    vsock: { guestCid: 2, udsPath: '/tmp/vsock.sock' },
+  });
+  const result = vmConfig.validate();
+  expect(result.valid).toBeFalse();
+  expect(result.errors).toContain('vsock.guestCid must be >= 3');
+});
+
+tap.test('VMConfig - constructor should not retain caller references', async () => {
+  const config: IMicroVMConfig = {
+    ...sampleConfig,
+    networkInterfaces: [{ ifaceId: 'eth0', guestMac: '02:00:00:00:00:01' }],
+    mmds: { version: 'V2', networkInterfaces: ['eth0'] },
+  };
+  const vmConfig = new VMConfig(config);
+
+  config.networkInterfaces![0].guestMac = '02:00:00:00:00:02';
+  config.mmds!.networkInterfaces.push('eth1');
+
+  expect(vmConfig.toNetworkInterfacePayload(vmConfig.config.networkInterfaces![0]).guest_mac)
+    .toEqual('02:00:00:00:00:01');
+  expect(vmConfig.toMmdsConfigPayload()!.network_interfaces).toEqual(['eth0']);
+});
+
 tap.test('VMConfig - toBootSourcePayload() should generate correct snake_case', async () => {
   const vmConfig = new VMConfig(sampleConfig);
   const payload = vmConfig.toBootSourcePayload();
@@ -144,6 +200,65 @@ tap.test('VMConfig - toBalloonPayload() should generate correct payload', async
   expect(payload!.stats_polling_interval_s).toEqual(5);
 });
 
+tap.test('VMConfig - toVsockPayload() should generate correct payload', async () => {
+  const config: IMicroVMConfig = {
+    ...sampleConfig,
+    vsock: { guestCid: 3, udsPath: '/tmp/vsock.sock' },
+  };
+  const vmConfig = new VMConfig(config);
+  const payload = vmConfig.toVsockPayload();
+  expect(payload).not.toBeNull();
+  expect(payload!.guest_cid).toEqual(3);
+  expect(payload!.uds_path).toEqual('/tmp/vsock.sock');
+});
+
+tap.test('VMConfig - toMmdsConfigPayload() should generate correct payload', async () => {
+  const config: IMicroVMConfig = {
+    ...sampleConfig,
+    mmds: { version: 'V2', networkInterfaces: ['eth0'] },
+  };
+  const vmConfig = new VMConfig(config);
+  const payload = vmConfig.toMmdsConfigPayload();
+  expect(payload).not.toBeNull();
+  expect(payload!.version).toEqual('V2');
+  expect(payload!.network_interfaces).toEqual(['eth0']);
+});
+
+tap.test('VMConfig - toMetricsPayload() should generate correct payload', async () => {
+  const config: IMicroVMConfig = {
+    ...sampleConfig,
+    metrics: { metricsPath: '/tmp/firecracker-metrics.fifo' },
+  };
+  const vmConfig = new VMConfig(config);
+  const payload = vmConfig.toMetricsPayload();
+  expect(payload).not.toBeNull();
+  expect(payload!.metrics_path).toEqual('/tmp/firecracker-metrics.fifo');
+});
+
+tap.test('VMConfig - toDrivePayload() should include rate limiter payloads', async () => {
+  const vmConfig = new VMConfig(sampleConfig);
+  const payload = vmConfig.toDrivePayload({
+    driveId: 'data',
+    pathOnHost: '/path/to/data.ext4',
+    isRootDevice: false,
+    rateLimiter: {
+      bandwidth: { size: 1000, refillTime: 2000, oneTimeBurst: 3000 },
+      ops: { size: 10, refillTime: 20, oneTimeBurst: 30 },
+    },
+  });
+
+  expect(payload.rate_limiter.bandwidth).toEqual({
+    size: 1000,
+    refill_time: 2000,
+    one_time_burst: 3000,
+  });
+  expect(payload.rate_limiter.ops).toEqual({
+    size: 10,
+    refill_time: 20,
+    one_time_burst: 30,
+  });
+});
+
 tap.test('VMConfig - toLoggerPayload() should generate correct payload', async () => {
   const config: IMicroVMConfig = {
     ...sampleConfig,
@@ -167,6 +282,269 @@ tap.test('SocketClient - URL construction', async () => {
   expect(client).toBeTruthy();
 });
 
+// ============================================================
+// BaseImageManager Tests
+// ============================================================
+
+tap.test('BaseImageManager - instantiation with defaults', async () => {
+  const manager = new BaseImageManager();
+  expect(manager.getCacheDir()).toEqual(path.join(os.tmpdir(), '.smartvm', 'base-images'));
+  expect(manager.getMaxStoredBaseImages()).toEqual(2);
+});
+
+tap.test('BaseImageManager - rejects invalid maxStoredBaseImages', async () => {
+  let error: unknown;
+  try {
+    new BaseImageManager({ maxStoredBaseImages: 0 });
+  } catch (err) {
+    error = err;
+  }
+
+  expect(error).toBeInstanceOf(SmartVMError);
+  expect((error as SmartVMError).code).toEqual('INVALID_BASE_IMAGE_CACHE_LIMIT');
+});
+
+tap.test('BaseImageManager - pruneBaseImageCache() should evict old bundles', async () => {
+  const cacheDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'smartvm-base-image-test-'));
+  const manager = new BaseImageManager({ cacheDir, maxStoredBaseImages: 2 });
+  const originalWarn = console.warn;
+  const warnings: string[] = [];
+  console.warn = (message?: any) => {
+    warnings.push(String(message));
+  };
+
+  const createManifest = async (bundleId: string, lastAccessedAt: string) => {
+    const bundleDir = path.join(cacheDir, bundleId);
+    await fs.promises.mkdir(bundleDir, { recursive: true });
+    const bundle: IBaseImageBundle = {
+      preset: 'lts',
+      arch: 'x86_64',
+      ciVersion: 'v1.7',
+      firecrackerVersion: 'v1.7.0',
+      bundleId,
+      bundleDir,
+      kernelImagePath: path.join(bundleDir, 'vmlinux'),
+      rootfsPath: path.join(bundleDir, 'rootfs.ext4'),
+      rootfsType: 'ext4',
+      rootfsIsReadOnly: false,
+      bootArgs: 'console=ttyS0 reboot=k panic=1 pci=off',
+      source: {
+        bucketUrl: 'https://s3.amazonaws.com/spec.ccfc.min',
+        kernelKey: 'kernel',
+        rootfsKey: 'rootfs',
+      },
+      createdAt: lastAccessedAt,
+      lastAccessedAt,
+    };
+    await fs.promises.writeFile(path.join(bundleDir, 'manifest.json'), `${JSON.stringify(bundle, null, 2)}\n`);
+  };
+
+  try {
+    await createManifest('old', '2024-01-01T00:00:00.000Z');
+    await createManifest('middle', '2024-01-02T00:00:00.000Z');
+    await createManifest('new', '2024-01-03T00:00:00.000Z');
+
+    const evicted = await manager.pruneBaseImageCache('new');
+    expect(evicted).toEqual(['old']);
+    expect(warnings.length).toEqual(1);
+    expect(warnings[0]).toInclude('Evicting old');
+    expect(fs.existsSync(path.join(cacheDir, 'old'))).toBeFalse();
+    expect(fs.existsSync(path.join(cacheDir, 'middle'))).toBeTrue();
+    expect(fs.existsSync(path.join(cacheDir, 'new'))).toBeTrue();
+  } finally {
+    console.warn = originalWarn;
+    await fs.promises.rm(cacheDir, { recursive: true, force: true });
+  }
+});
+
+tap.test('BaseImageManager - ensureBaseImage() should copy hosted manifest artifacts', async () => {
+  const workDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'smartvm-hosted-image-test-'));
+  const cacheDir = path.join(workDir, 'cache');
+  const assetsDir = path.join(workDir, 'assets');
+  await fs.promises.mkdir(assetsDir, { recursive: true });
+
+  const kernelBuffer = Buffer.from('fake-kernel');
+  const rootfsBuffer = Buffer.from('fake-rootfs');
+  const kernelPath = path.join(assetsDir, 'vmlinux-test');
+  const rootfsPath = path.join(assetsDir, 'rootfs-test.ext4');
+  await fs.promises.writeFile(kernelPath, kernelBuffer);
+  await fs.promises.writeFile(rootfsPath, rootfsBuffer);
+
+  const manifest: IBaseImageHostedManifest = {
+    schemaVersion: 1,
+    bundleId: 'smartvm-minimal-test',
+    name: 'SmartVM minimal test bundle',
+    arch: 'x86_64',
+    firecrackerVersion: 'v1.15.1',
+    rootfsType: 'ext4',
+    rootfsIsReadOnly: false,
+    bootArgs: 'console=ttyS0 reboot=k panic=1 pci=off',
+    kernel: {
+      path: kernelPath,
+      fileName: 'vmlinux',
+      sha256: sha256Buffer(kernelBuffer),
+      sizeBytes: kernelBuffer.length,
+    },
+    rootfs: {
+      path: rootfsPath,
+      fileName: 'rootfs.ext4',
+      sha256: sha256Buffer(rootfsBuffer),
+      sizeBytes: rootfsBuffer.length,
+    },
+  };
+  const manifestPath = path.join(workDir, 'manifest.json');
+  await fs.promises.writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+
+  try {
+    const manager = new BaseImageManager({ cacheDir });
+    const bundle = await manager.ensureBaseImage({ manifestPath });
+
+    expect(bundle.preset).toEqual('hosted');
+    expect(bundle.bundleId).toEqual('smartvm-minimal-test');
+    expect(bundle.firecrackerVersion).toEqual('v1.15.1');
+    expect(bundle.source.type).toEqual('hosted-manifest');
+    expect(bundle.source.manifestPath).toEqual(manifestPath);
+    expect(fs.existsSync(bundle.kernelImagePath)).toBeTrue();
+    expect(fs.existsSync(bundle.rootfsPath)).toBeTrue();
+    expect(bundle.checksums!.kernelSha256).toEqual(sha256Buffer(kernelBuffer));
+    expect(bundle.checksums!.rootfsSha256).toEqual(sha256Buffer(rootfsBuffer));
+  } finally {
+    await fs.promises.rm(workDir, { recursive: true, force: true });
+  }
+});
+
+tap.test('BaseImageManager - ensureBaseImage() should redownload corrupted cached artifacts', async () => {
+  const workDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'smartvm-hosted-image-cache-test-'));
+  const cacheDir = path.join(workDir, 'cache');
+  const assetsDir = path.join(workDir, 'assets');
+  await fs.promises.mkdir(assetsDir, { recursive: true });
+
+  const kernelBuffer = Buffer.from('fresh-kernel');
+  const rootfsBuffer = Buffer.from('fresh-rootfs');
+  const kernelPath = path.join(assetsDir, 'vmlinux-test');
+  const rootfsPath = path.join(assetsDir, 'rootfs-test.ext4');
+  await fs.promises.writeFile(kernelPath, kernelBuffer);
+  await fs.promises.writeFile(rootfsPath, rootfsBuffer);
+
+  const manifest: IBaseImageHostedManifest = {
+    schemaVersion: 1,
+    bundleId: 'smartvm-corruption-test',
+    arch: 'x86_64',
+    firecrackerVersion: 'v1.15.1',
+    rootfsType: 'ext4',
+    kernel: {
+      path: kernelPath,
+      fileName: 'vmlinux',
+      sha256: sha256Buffer(kernelBuffer),
+      sizeBytes: kernelBuffer.length,
+    },
+    rootfs: {
+      path: rootfsPath,
+      fileName: 'rootfs.ext4',
+      sha256: sha256Buffer(rootfsBuffer),
+      sizeBytes: rootfsBuffer.length,
+    },
+  };
+  const manifestPath = path.join(workDir, 'manifest.json');
+  await fs.promises.writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+
+  try {
+    const manager = new BaseImageManager({ cacheDir });
+    const firstBundle = await manager.ensureBaseImage({ manifestPath });
+    await fs.promises.writeFile(firstBundle.kernelImagePath, 'tampered-kernel');
+
+    const secondBundle = await manager.ensureBaseImage({ manifestPath });
+    expect(await fs.promises.readFile(secondBundle.kernelImagePath, 'utf8')).toEqual('fresh-kernel');
+    expect(secondBundle.checksums!.kernelSha256).toEqual(sha256Buffer(kernelBuffer));
+  } finally {
+    await fs.promises.rm(workDir, { recursive: true, force: true });
+  }
+});
+
+tap.test('BaseImageManager - ensureBaseImage() should reject hosted manifest arch mismatch', async () => {
+  const workDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'smartvm-hosted-image-invalid-test-'));
+  const manifestPath = path.join(workDir, 'manifest.json');
+  const manifest: IBaseImageHostedManifest = {
+    schemaVersion: 1,
+    bundleId: 'smartvm-invalid-arch-test',
+    arch: 'aarch64',
+    firecrackerVersion: 'v1.15.1',
+    rootfsType: 'ext4',
+    kernel: { path: path.join(workDir, 'vmlinux') },
+    rootfs: { path: path.join(workDir, 'rootfs.ext4') },
+  };
+  await fs.promises.writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+
+  try {
+    const manager = new BaseImageManager({ cacheDir: path.join(workDir, 'cache'), arch: 'x86_64' });
+    const error = await getRejectedError(manager.ensureBaseImage({ manifestPath }));
+    expect(error).toBeInstanceOf(SmartVMError);
+    expect((error as SmartVMError).code).toEqual('INVALID_BASE_IMAGE_MANIFEST');
+  } finally {
+    await fs.promises.rm(workDir, { recursive: true, force: true });
+  }
+});
+
+tap.test('BaseImageManager - ensureBaseImage() should reject hosted manifest fileName traversal', async () => {
+  const workDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'smartvm-hosted-image-filename-test-'));
+  const manifestPath = path.join(workDir, 'manifest.json');
+  const manifest: IBaseImageHostedManifest = {
+    schemaVersion: 1,
+    bundleId: 'smartvm-invalid-filename-test',
+    arch: 'x86_64',
+    firecrackerVersion: 'v1.15.1',
+    rootfsType: 'ext4',
+    kernel: { path: path.join(workDir, 'vmlinux'), fileName: '../vmlinux' },
+    rootfs: { path: path.join(workDir, 'rootfs.ext4'), fileName: 'rootfs.ext4' },
+  };
+  await fs.promises.writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+
+  try {
+    const manager = new BaseImageManager({ cacheDir: path.join(workDir, 'cache') });
+    const error = await getRejectedError(manager.ensureBaseImage({ manifestPath }));
+    expect(error).toBeInstanceOf(SmartVMError);
+    expect((error as SmartVMError).code).toEqual('INVALID_BASE_IMAGE_MANIFEST');
+  } finally {
+    await fs.promises.rm(workDir, { recursive: true, force: true });
+  }
+});
+
+tap.test('BaseImageManager - ensureBaseImage() should reject hosted URL artifacts without sha256', async () => {
+  const workDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'smartvm-hosted-image-url-test-'));
+  const manifestPath = path.join(workDir, 'manifest.json');
+  const manifest: IBaseImageHostedManifest = {
+    schemaVersion: 1,
+    bundleId: 'smartvm-invalid-url-test',
+    arch: 'x86_64',
+    firecrackerVersion: 'v1.15.1',
+    rootfsType: 'ext4',
+    kernel: { url: 'https://example.com/vmlinux' },
+    rootfs: { path: path.join(workDir, 'rootfs.ext4') },
+  };
+  await fs.promises.writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+
+  try {
+    const manager = new BaseImageManager({ cacheDir: path.join(workDir, 'cache') });
+    const error = await getRejectedError(manager.ensureBaseImage({ manifestPath }));
+    expect(error).toBeInstanceOf(SmartVMError);
+    expect((error as SmartVMError).code).toEqual('INVALID_BASE_IMAGE_MANIFEST');
+  } finally {
+    await fs.promises.rm(workDir, { recursive: true, force: true });
+  }
+});
+
+tap.test('BaseImageManager - hosted preset should require a manifest', async () => {
+  const workDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'smartvm-hosted-image-missing-test-'));
+  try {
+    const manager = new BaseImageManager({ cacheDir: path.join(workDir, 'cache') });
+    const error = await getRejectedError(manager.ensureBaseImage({ preset: 'hosted' }));
+    expect(error).toBeInstanceOf(SmartVMError);
+    expect((error as SmartVMError).code).toEqual('BASE_IMAGE_MANIFEST_FAILED');
+  } finally {
+    await fs.promises.rm(workDir, { recursive: true, force: true });
+  }
+});
+
 // ============================================================
 // NetworkManager Tests
 // ============================================================
@@ -181,6 +559,65 @@ tap.test('NetworkManager - allocateIp() should allocate sequential IPs', async (
   expect(ip3).toEqual('172.30.0.4');
 });
 
+tap.test('NetworkManager - allocateIp() should normalize non-network CIDR input', async () => {
+  const nm = new NetworkManager({ subnet: '10.20.30.17/29' });
+  expect(nm.allocateIp()).toEqual('10.20.30.18');
+  expect(nm.allocateIp()).toEqual('10.20.30.19');
+});
+
+tap.test('NetworkManager - allocateIp() should fail when subnet is exhausted', async () => {
+  const nm = new NetworkManager({ subnet: '192.168.100.0/30' });
+  expect(nm.allocateIp()).toEqual('192.168.100.2');
+
+  let error: unknown;
+  try {
+    nm.allocateIp();
+  } catch (err) {
+    error = err;
+  }
+
+  expect(error).toBeInstanceOf(SmartVMError);
+  expect((error as SmartVMError).code).toEqual('IP_EXHAUSTED');
+});
+
+tap.test('NetworkManager - constructor should reject invalid subnet input', async () => {
+  let error: unknown;
+  try {
+    new NetworkManager({ subnet: '10.0.0.0/31' });
+  } catch (err) {
+    error = err;
+  }
+
+  expect(error).toBeInstanceOf(SmartVMError);
+  expect((error as SmartVMError).code).toEqual('INVALID_SUBNET');
+});
+
+tap.test('NetworkManager - constructor should reject malformed IPv4 octets', async () => {
+  for (const subnet of ['10..0.1/24', '10.0x10.0.1/24', '10.0.0.1 /24']) {
+    let error: unknown;
+    try {
+      new NetworkManager({ subnet });
+    } catch (err) {
+      error = err;
+    }
+
+    expect(error).toBeInstanceOf(SmartVMError);
+    expect((error as SmartVMError).code).toEqual('INVALID_SUBNET');
+  }
+});
+
+tap.test('NetworkManager - constructor should reject invalid bridge names', async () => {
+  let error: unknown;
+  try {
+    new NetworkManager({ bridgeName: 'bad bridge' });
+  } catch (err) {
+    error = err;
+  }
+
+  expect(error).toBeInstanceOf(SmartVMError);
+  expect((error as SmartVMError).code).toEqual('INVALID_INTERFACE_NAME');
+});
+
 tap.test('NetworkManager - generateMac() should generate locally-administered MACs', async () => {
   const nm = new NetworkManager();
   const mac1 = nm.generateMac('vm1', 'eth0');
@@ -228,6 +665,218 @@ tap.test('NetworkManager - getGuestNetworkBootArgs() should format correctly', a
   expect(bootArgs).toEqual('ip=172.30.0.2::172.30.0.1:255.255.255.0::eth0:off');
 });
 
+tap.test('NetworkManager - constructor should accept valid egress firewall config', async () => {
+  const nm = new NetworkManager({
+    firewall: {
+      egress: {
+        defaultAction: 'deny',
+        rules: [
+          { action: 'allow', to: '1.1.1.1', protocol: 'tcp', ports: [80, 443] },
+          { action: 'deny', to: '10.0.0.0/8' },
+          { action: 'allow', protocol: 'icmp' },
+        ],
+      },
+    },
+  });
+
+  expect(nm).toBeTruthy();
+});
+
+tap.test('NetworkManager - constructor should reject invalid firewall CIDRs and ports', async () => {
+  const invalidCidrError = getThrownError(() => new NetworkManager({
+    firewall: {
+      egress: {
+        rules: [{ action: 'allow', to: '300.1.1.1/32' }],
+      },
+    },
+  }));
+  expect(invalidCidrError).toBeInstanceOf(SmartVMError);
+  expect((invalidCidrError as SmartVMError).code).toEqual('INVALID_FIREWALL_CONFIG');
+
+  const invalidPortError = getThrownError(() => new NetworkManager({
+    firewall: {
+      egress: {
+        rules: [{ action: 'allow', protocol: 'icmp', ports: 53 }],
+      },
+    },
+  }));
+  expect(invalidPortError).toBeInstanceOf(SmartVMError);
+  expect((invalidPortError as SmartVMError).code).toEqual('INVALID_FIREWALL_CONFIG');
+});
+
+tap.test('NetworkManager - constructor should accept valid WireGuard managed config', async () => {
+  const nm = new NetworkManager({
+    wireguard: {
+      interfaceName: 'svwgtest0',
+      routeTable: 51821,
+      config: `
+# comments are ignored
+[Interface]
+PrivateKey = test-private-key
+Address = 10.70.0.2/32
+DNS = 1.1.1.1
+MTU = 1420
+Table = off
+
+[Peer]
+PublicKey = test-public-key
+AllowedIPs = 0.0.0.0/0
+Endpoint = 203.0.113.10:51820
+PersistentKeepalive = 25
+`,
+    },
+  });
+
+  expect(nm).toBeTruthy();
+});
+
+tap.test('NetworkManager - constructor should reject unsafe WireGuard hook fields', async () => {
+  const error = getThrownError(() => new NetworkManager({
+    wireguard: {
+      config: `
+[Interface]
+PrivateKey = test-private-key
+Address = 10.70.0.2/32
+PostUp = iptables -A OUTPUT -j ACCEPT
+`,
+    },
+  }));
+
+  expect(error).toBeInstanceOf(SmartVMError);
+  expect((error as SmartVMError).code).toEqual('INVALID_WIREGUARD_CONFIG');
+});
+
+tap.test('NetworkManager - constructor should reject IPv6 WireGuard AllowedIPs', async () => {
+  const error = getThrownError(() => new NetworkManager({
+    wireguard: {
+      config: `
+[Interface]
+PrivateKey = test-private-key
+Address = 10.70.0.2/32
+
+[Peer]
+PublicKey = test-public-key
+AllowedIPs = ::/0
+`,
+    },
+  }));
+
+  expect(error).toBeInstanceOf(SmartVMError);
+  expect((error as SmartVMError).code).toEqual('INVALID_WIREGUARD_CONFIG');
+});
+
+tap.test('NetworkManager - constructor should reject mixed WireGuard modes', async () => {
+  const error = getThrownError(() => new NetworkManager({
+    wireguard: {
+      existingInterface: 'wg0',
+      config: '[Interface]\nPrivateKey = test-private-key\nAddress = 10.70.0.2/32\n',
+    } as any,
+  }));
+
+  expect(error).toBeInstanceOf(SmartVMError);
+  expect((error as SmartVMError).code).toEqual('INVALID_WIREGUARD_CONFIG');
+});
+
+// ============================================================
+// MicroVM Tests
+// ============================================================
+
+tap.test('MicroVM - invalid lifecycle calls should throw SmartVMError', async () => {
+  const vm = new MicroVM(
+    'lifecycle-vm',
+    sampleConfig,
+    '/bin/false',
+    '/tmp/smartvm-lifecycle.sock',
+    new NetworkManager(),
+  );
+
+  const pauseError = await getRejectedError(vm.pause());
+  expect(pauseError).toBeInstanceOf(SmartVMError);
+  expect((pauseError as SmartVMError).code).toEqual('INVALID_STATE');
+
+  const infoError = await getRejectedError(vm.getInfo());
+  expect(infoError).toBeInstanceOf(SmartVMError);
+  expect((infoError as SmartVMError).code).toEqual('NO_CLIENT');
+});
+
+tap.test('MicroVM - start() should stage writable drives ephemerally and clean them up on failure', async () => {
+  const workDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'smartvm-ephemeral-drive-test-'));
+  const runtimeDir = path.join(workDir, 'runtime');
+  const sourceRootfs = path.join(workDir, 'rootfs.ext4');
+  await fs.promises.writeFile(sourceRootfs, 'persistent-rootfs');
+
+  const config: IMicroVMConfig = {
+    ...sampleConfig,
+    id: 'ephemeral-vm',
+    drives: [
+      {
+        driveId: 'rootfs',
+        pathOnHost: sourceRootfs,
+        isRootDevice: true,
+        isReadOnly: false,
+      },
+    ],
+    networkInterfaces: [],
+  };
+  const vm = new MicroVM(
+    'ephemeral-vm',
+    config,
+    '/bin/false',
+    path.join(runtimeDir, 'ephemeral-vm', 'firecracker.sock'),
+    new NetworkManager(),
+    { runtimeDir },
+  );
+
+  try {
+    const error = await getRejectedError(vm.start());
+    expect(error).toBeInstanceOf(SmartVMError);
+    expect(fs.existsSync(path.join(runtimeDir, 'ephemeral-vm'))).toBeFalse();
+    expect(await fs.promises.readFile(sourceRootfs, 'utf8')).toEqual('persistent-rootfs');
+    expect(vm.getVMConfig().config.drives![0].pathOnHost).not.toEqual(sourceRootfs);
+  } finally {
+    await fs.promises.rm(workDir, { recursive: true, force: true });
+  }
+});
+
+tap.test('MicroVM - start() should honor per-drive ephemeral opt-out', async () => {
+  const workDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'smartvm-persistent-drive-test-'));
+  const runtimeDir = path.join(workDir, 'runtime');
+  const sourceRootfs = path.join(workDir, 'rootfs.ext4');
+  await fs.promises.writeFile(sourceRootfs, 'persistent-rootfs');
+
+  const config: IMicroVMConfig = {
+    ...sampleConfig,
+    id: 'persistent-vm',
+    drives: [
+      {
+        driveId: 'rootfs',
+        pathOnHost: sourceRootfs,
+        isRootDevice: true,
+        isReadOnly: false,
+        ephemeral: false,
+      },
+    ],
+    networkInterfaces: [],
+  };
+  const vm = new MicroVM(
+    'persistent-vm',
+    config,
+    '/bin/false',
+    path.join(runtimeDir, 'persistent-vm', 'firecracker.sock'),
+    new NetworkManager(),
+    { runtimeDir },
+  );
+
+  try {
+    const error = await getRejectedError(vm.start());
+    expect(error).toBeInstanceOf(SmartVMError);
+    expect(vm.getVMConfig().config.drives![0].pathOnHost).toEqual(sourceRootfs);
+    expect(fs.existsSync(path.join(runtimeDir, 'persistent-vm'))).toBeFalse();
+  } finally {
+    await fs.promises.rm(workDir, { recursive: true, force: true });
+  }
+});
+
 // ============================================================
 // SmartVM Tests
 // ============================================================
@@ -236,7 +885,11 @@ tap.test('SmartVM - instantiation with defaults', async () => {
   const smartvm = new SmartVM();
   expect(smartvm).toBeTruthy();
   expect(smartvm.imageManager).toBeTruthy();
+  expect(smartvm.baseImageManager).toBeTruthy();
   expect(smartvm.networkManager).toBeTruthy();
+  if (fs.existsSync('/dev/shm')) {
+    expect(smartvm.getRuntimeDir()).toEqual('/dev/shm/.smartvm/runtime');
+  }
   expect(smartvm.vmCount).toEqual(0);
   expect(smartvm.listVMs()).toHaveLength(0);
 });
@@ -251,4 +904,45 @@ tap.test('SmartVM - instantiation with custom options', async () => {
   expect(smartvm).toBeTruthy();
 });
 
+tap.test('SmartVM - should forward firewall and WireGuard options to NetworkManager', async () => {
+  const firewall = {
+    egress: {
+      defaultAction: 'deny' as const,
+      rules: [{ action: 'allow' as const, to: '1.1.1.1', protocol: 'tcp' as const, ports: 443 }],
+    },
+  };
+  const wireguard = {
+    existingInterface: 'wgsmartvm0',
+    routeAllVmTraffic: false,
+  };
+  const smartvm = new SmartVM({
+    dataDir: '/tmp/smartvm-test',
+    firecrackerBinaryPath: '/bin/false',
+    firewall,
+    wireguard,
+  });
+
+  try {
+    expect((smartvm.networkManager as any).firewall).toEqual(firewall);
+    expect((smartvm.networkManager as any).wireguard).toEqual(wireguard);
+  } finally {
+    await smartvm.cleanup();
+  }
+});
+
+tap.test('SmartVM - createVM() should track created VMs', async () => {
+  const smartvm = new SmartVM({
+    dataDir: '/tmp/smartvm-test',
+    firecrackerBinaryPath: '/bin/false',
+  });
+  const vm = await smartvm.createVM(sampleConfig);
+
+  expect(smartvm.vmCount).toEqual(1);
+  expect(smartvm.getVM(vm.id)).toEqual(vm);
+  expect(smartvm.listVMs()).toEqual([vm.id]);
+
+  await smartvm.cleanup();
+  expect(smartvm.vmCount).toEqual(0);
+});
+
 export default tap.start();

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartvm',
-  version: '1.1.1',
+  version: '1.4.1',
   description: 'A TypeScript module wrapping Amazon Firecracker VMM for managing lightweight microVMs'
 }

ts/classes.baseimagemanager.ts

@@ -0,0 +1,713 @@
+import * as plugins from './plugins.js';
+import type {
+  IBaseImageArtifactManifest,
+  IBaseImageBundle,
+  IBaseImageHostedManifest,
+  IBaseImageManagerOptions,
+  IEnsureBaseImageOptions,
+  TBaseImagePreset,
+  TBaseImageRootfsType,
+  TFirecrackerArch,
+} from './interfaces/index.js';
+import { SmartVMError } from './interfaces/index.js';
+
+const FIRECRACKER_CI_BUCKET_URL = 'https://s3.amazonaws.com/spec.ccfc.min';
+const DEFAULT_MAX_STORED_BASE_IMAGES = 2;
+const LTS_CI_VERSION = 'v1.7';
+const LTS_FIRECRACKER_VERSION = 'v1.7.0';
+
+type TShellExecResult = Awaited<ReturnType<InstanceType<typeof plugins.smartshell.Smartshell>['execSpawn']>>;
+
+interface IResolvedBaseImageSource {
+  preset: TBaseImagePreset;
+  arch: TFirecrackerArch;
+  ciVersion: string;
+  firecrackerVersion: string;
+  kernelKey?: string;
+  rootfsKey?: string;
+  kernelUrl?: string;
+  rootfsUrl?: string;
+  kernelSourcePath?: string;
+  rootfsSourcePath?: string;
+  kernelFileName?: string;
+  rootfsFileName?: string;
+  expectedKernelSha256?: string;
+  expectedRootfsSha256?: string;
+  expectedKernelBytes?: number;
+  expectedRootfsBytes?: number;
+  rootfsType: TBaseImageRootfsType;
+  rootfsIsReadOnly: boolean;
+  bundleId: string;
+  bootArgs: string;
+  source: IBaseImageBundle['source'];
+}
+
+function getErrorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/**
+ * Downloads and retains Firecracker CI base images for integration testing.
+ */
+export class BaseImageManager {
+  private arch: TFirecrackerArch;
+  private cacheDir: string;
+  private maxStoredBaseImages: number;
+  private hostedManifestUrl?: string;
+  private hostedManifestPath?: string;
+  private shell: InstanceType<typeof plugins.smartshell.Smartshell>;
+
+  constructor(options: IBaseImageManagerOptions = {}) {
+    this.arch = options.arch || 'x86_64';
+    this.cacheDir = options.cacheDir || plugins.path.join(plugins.os.tmpdir(), '.smartvm', 'base-images');
+    this.maxStoredBaseImages = options.maxStoredBaseImages ?? DEFAULT_MAX_STORED_BASE_IMAGES;
+    this.hostedManifestUrl = options.hostedManifestUrl;
+    this.hostedManifestPath = options.hostedManifestPath;
+    if (!Number.isInteger(this.maxStoredBaseImages) || this.maxStoredBaseImages < 1) {
+      throw new SmartVMError(
+        'maxStoredBaseImages must be a positive integer',
+        'INVALID_BASE_IMAGE_CACHE_LIMIT',
+      );
+    }
+    this.shell = new plugins.smartshell.Smartshell({ executor: 'bash' });
+  }
+
+  public getCacheDir(): string {
+    return this.cacheDir;
+  }
+
+  public getMaxStoredBaseImages(): number {
+    return this.maxStoredBaseImages;
+  }
+
+  /**
+   * Ensure a base image bundle exists locally and return its paths.
+   */
+  public async ensureBaseImage(options: IEnsureBaseImageOptions = {}): Promise<IBaseImageBundle> {
+    const source = await this.resolveBaseImageSource(options);
+    const bundleDir = plugins.path.join(this.cacheDir, source.bundleId);
+    const manifestPath = this.getManifestPath(bundleDir);
+
+    const cachedBundle = options.forceDownload ? undefined : await this.readCompleteBundle(bundleDir);
+    if (cachedBundle) {
+      const updatedBundle = {
+        ...cachedBundle,
+        lastAccessedAt: new Date().toISOString(),
+      };
+      await this.writeBundleManifest(updatedBundle);
+      await this.pruneBaseImageCache(updatedBundle.bundleId);
+      return updatedBundle;
+    }
+
+    await plugins.fs.promises.mkdir(bundleDir, { recursive: true });
+
+    const kernelFileName = source.kernelFileName || this.getSourceFileName(source.kernelUrl || source.kernelSourcePath || source.kernelKey!, 'vmlinux');
+    const rootfsFileName = source.rootfsFileName || this.getSourceFileName(source.rootfsUrl || source.rootfsSourcePath || source.rootfsKey!, `rootfs.${source.rootfsType}`);
+    const kernelPath = this.resolveBundleFilePath(bundleDir, kernelFileName);
+    const rootfsPath = this.resolveBundleFilePath(bundleDir, rootfsFileName);
+
+    try {
+      await this.prepareArtifact({
+        url: source.kernelUrl || (source.kernelKey ? this.keyToUrl(source.kernelKey) : undefined),
+        sourcePath: source.kernelSourcePath,
+        targetPath: kernelPath,
+        expectedSha256: source.expectedKernelSha256,
+        expectedBytes: source.expectedKernelBytes,
+      });
+      await this.prepareArtifact({
+        url: source.rootfsUrl || (source.rootfsKey ? this.keyToUrl(source.rootfsKey) : undefined),
+        sourcePath: source.rootfsSourcePath,
+        targetPath: rootfsPath,
+        expectedSha256: source.expectedRootfsSha256,
+        expectedBytes: source.expectedRootfsBytes,
+      });
+
+      const now = new Date().toISOString();
+      const bundle: IBaseImageBundle = {
+        preset: source.preset,
+        arch: source.arch,
+        ciVersion: source.ciVersion,
+        firecrackerVersion: source.firecrackerVersion,
+        bundleId: source.bundleId,
+        bundleDir,
+        kernelImagePath: kernelPath,
+        rootfsPath,
+        rootfsType: source.rootfsType,
+        rootfsIsReadOnly: source.rootfsIsReadOnly,
+        bootArgs: source.bootArgs,
+        source: source.source,
+        checksums: {
+          kernelSha256: await this.sha256File(kernelPath),
+          rootfsSha256: await this.sha256File(rootfsPath),
+        },
+        sizes: {
+          kernelBytes: (await plugins.fs.promises.stat(kernelPath)).size,
+          rootfsBytes: (await plugins.fs.promises.stat(rootfsPath)).size,
+        },
+        createdAt: now,
+        lastAccessedAt: now,
+      };
+
+      await this.writeBundleManifest(bundle);
+      await this.pruneBaseImageCache(bundle.bundleId);
+      return bundle;
+    } catch (err) {
+      await plugins.fs.promises.rm(bundleDir, { recursive: true, force: true });
+      throw new SmartVMError(
+        `Failed to prepare base image bundle ${source.bundleId}: ${getErrorMessage(err)}`,
+        'BASE_IMAGE_PREPARE_FAILED',
+      );
+    }
+  }
+
+  /**
+   * Prune cached base image bundles according to the retention limit.
+   */
+  public async pruneBaseImageCache(keepBundleId?: string): Promise<string[]> {
+    await plugins.fs.promises.mkdir(this.cacheDir, { recursive: true });
+    const bundles = await this.listCachedBundles();
+    bundles.sort((a, b) => {
+      if (keepBundleId) {
+        if (a.bundleId === keepBundleId) return -1;
+        if (b.bundleId === keepBundleId) return 1;
+      }
+      return Date.parse(b.lastAccessedAt) - Date.parse(a.lastAccessedAt);
+    });
+
+    const evicted: string[] = [];
+    for (const bundle of bundles.slice(this.maxStoredBaseImages)) {
+      console.warn(
+        `[smartvm] Base image cache stores at most ${this.maxStoredBaseImages} bundle(s). ` +
+        `Evicting ${bundle.bundleId} from ${bundle.bundleDir}. Configure maxStoredBaseImages to change this behavior.`,
+      );
+      await plugins.fs.promises.rm(bundle.bundleDir, { recursive: true, force: true });
+      evicted.push(bundle.bundleId);
+    }
+    return evicted;
+  }
+
+  private async resolveBaseImageSource(options: IEnsureBaseImageOptions): Promise<IResolvedBaseImageSource> {
+    const arch = options.arch || this.arch;
+    const manifestUrl = options.manifestUrl || this.hostedManifestUrl;
+    const manifestPath = options.manifestPath || this.hostedManifestPath;
+    if (manifestUrl || manifestPath) {
+      return this.resolveHostedManifestSource({ arch, manifestUrl, manifestPath });
+    }
+
+    const preset = options.preset || 'latest';
+    if (preset === 'hosted') {
+      throw new SmartVMError(
+        'The hosted base image preset requires manifestUrl, manifestPath, or a manager-level hosted manifest option',
+        'BASE_IMAGE_MANIFEST_FAILED',
+      );
+    }
+    const firecrackerVersion = preset === 'latest'
+      ? await this.getLatestFirecrackerVersion()
+      : LTS_FIRECRACKER_VERSION;
+    const ciVersion = preset === 'latest'
+      ? firecrackerVersion.split('.').slice(0, 2).join('.')
+      : LTS_CI_VERSION;
+
+    const keys = await this.listCiKeys(ciVersion, arch);
+    const kernelKey = this.selectKernelKey(keys);
+    const rootfsKey = this.selectRootfsKey(keys);
+    const rootfsType = rootfsKey.endsWith('.ext4') ? 'ext4' : 'squashfs';
+    const bundleId = this.buildBundleId(preset, ciVersion, arch, kernelKey, rootfsKey);
+
+    return {
+      preset,
+      arch,
+      ciVersion,
+      firecrackerVersion,
+      kernelKey,
+      rootfsKey,
+      rootfsType,
+      rootfsIsReadOnly: rootfsType === 'squashfs',
+      bundleId,
+      bootArgs: this.buildBootArgs(arch, rootfsType),
+      source: {
+        type: 'firecracker-ci',
+        bucketUrl: FIRECRACKER_CI_BUCKET_URL,
+        kernelKey,
+        rootfsKey,
+      },
+    };
+  }
+
+  private async resolveHostedManifestSource(options: {
+    arch: TFirecrackerArch;
+    manifestUrl?: string;
+    manifestPath?: string;
+  }): Promise<IResolvedBaseImageSource> {
+    const manifest = await this.loadHostedManifest(options);
+    this.validateHostedManifest(manifest, options.arch);
+    this.getArtifactSource(manifest.kernel, 'kernel');
+    this.getArtifactSource(manifest.rootfs, 'rootfs');
+
+    return {
+      preset: 'hosted',
+      arch: manifest.arch,
+      ciVersion: 'hosted',
+      firecrackerVersion: manifest.firecrackerVersion,
+      kernelUrl: manifest.kernel.url,
+      rootfsUrl: manifest.rootfs.url,
+      kernelSourcePath: manifest.kernel.path,
+      rootfsSourcePath: manifest.rootfs.path,
+      kernelFileName: manifest.kernel.fileName,
+      rootfsFileName: manifest.rootfs.fileName,
+      expectedKernelSha256: manifest.kernel.sha256,
+      expectedRootfsSha256: manifest.rootfs.sha256,
+      expectedKernelBytes: manifest.kernel.sizeBytes,
+      expectedRootfsBytes: manifest.rootfs.sizeBytes,
+      rootfsType: manifest.rootfsType,
+      rootfsIsReadOnly: manifest.rootfsIsReadOnly ?? manifest.rootfsType === 'squashfs',
+      bundleId: this.sanitizeBundleId(manifest.bundleId),
+      bootArgs: manifest.bootArgs || this.buildBootArgs(manifest.arch, manifest.rootfsType),
+      source: {
+        type: 'hosted-manifest',
+        manifestUrl: options.manifestUrl,
+        manifestPath: options.manifestPath,
+        kernelUrl: manifest.kernel.url,
+        rootfsUrl: manifest.rootfs.url,
+        kernelSourcePath: manifest.kernel.path,
+        rootfsSourcePath: manifest.rootfs.path,
+      },
+    };
+  }
+
+  private async getLatestFirecrackerVersion(): Promise<string> {
+    try {
+      const result = await this.shell.execSpawn('curl', [
+        '-fsSLI',
+        '-o',
+        '/dev/null',
+        '-w',
+        '%{url_effective}',
+        'https://github.com/firecracker-microvm/firecracker/releases/latest',
+      ], { silent: true });
+      if (result.exitCode !== 0) {
+        const output = (result.stderr || result.stdout || '').trim();
+        throw new Error(`curl exited with code ${result.exitCode}${output ? `: ${output}` : ''}`);
+      }
+
+      const match = result.stdout.trim().match(/\/releases\/tag\/(v\d+\.\d+\.\d+)$/);
+      if (!match) {
+        throw new Error(`Could not parse latest Firecracker release URL: ${result.stdout.trim()}`);
+      }
+      return match[1];
+    } catch (err) {
+      throw new SmartVMError(
+        `Failed to resolve latest Firecracker version: ${getErrorMessage(err)}`,
+        'VERSION_FETCH_FAILED',
+      );
+    }
+  }
+
+  private async loadHostedManifest(options: {
+    manifestUrl?: string;
+    manifestPath?: string;
+  }): Promise<IBaseImageHostedManifest> {
+    try {
+      let raw: string;
+      if (options.manifestPath) {
+        raw = await plugins.fs.promises.readFile(options.manifestPath, 'utf8');
+      } else if (options.manifestUrl) {
+        const response = await plugins.SmartRequest.create()
+          .url(options.manifestUrl)
+          .get();
+        raw = await response.text();
+      } else {
+        throw new Error('manifestUrl or manifestPath is required');
+      }
+      return JSON.parse(raw) as IBaseImageHostedManifest;
+    } catch (err) {
+      throw new SmartVMError(
+        `Failed to load hosted base image manifest: ${getErrorMessage(err)}`,
+        'BASE_IMAGE_MANIFEST_FAILED',
+      );
+    }
+  }
+
+  private validateHostedManifest(manifest: IBaseImageHostedManifest, expectedArch: TFirecrackerArch): void {
+    if (manifest.schemaVersion !== 1) {
+      throw new SmartVMError(
+        'Hosted base image manifest schemaVersion must be 1',
+        'INVALID_BASE_IMAGE_MANIFEST',
+      );
+    }
+    if (!manifest.bundleId || !/^[a-zA-Z0-9._-]+$/.test(manifest.bundleId)) {
+      throw new SmartVMError(
+        'Hosted base image manifest bundleId must use only letters, numbers, dot, underscore, and dash',
+        'INVALID_BASE_IMAGE_MANIFEST',
+      );
+    }
+    if (manifest.arch !== expectedArch) {
+      throw new SmartVMError(
+        `Hosted base image arch '${manifest.arch}' does not match requested arch '${expectedArch}'`,
+        'INVALID_BASE_IMAGE_MANIFEST',
+      );
+    }
+    if (!manifest.firecrackerVersion || !/^v\d+\.\d+\.\d+$/.test(manifest.firecrackerVersion)) {
+      throw new SmartVMError(
+        'Hosted base image manifest firecrackerVersion must look like v1.15.1',
+        'INVALID_BASE_IMAGE_MANIFEST',
+      );
+    }
+    if (manifest.rootfsType !== 'ext4' && manifest.rootfsType !== 'squashfs') {
+      throw new SmartVMError(
+        'Hosted base image manifest rootfsType must be ext4 or squashfs',
+        'INVALID_BASE_IMAGE_MANIFEST',
+      );
+    }
+    this.validateArtifactManifest(manifest.kernel, 'kernel');
+    this.validateArtifactManifest(manifest.rootfs, 'rootfs');
+  }
+
+  private validateArtifactManifest(artifact: IBaseImageArtifactManifest, label: string): void {
+    this.getArtifactSource(artifact, label);
+    if (artifact.fileName !== undefined) {
+      this.validateArtifactFileName(artifact.fileName, label);
+    }
+    if (artifact.url && !artifact.sha256) {
+      throw new SmartVMError(
+        `Hosted base image manifest ${label} artifact with url requires sha256`,
+        'INVALID_BASE_IMAGE_MANIFEST',
+      );
+    }
+    if (artifact.sha256 !== undefined && !/^[a-fA-F0-9]{64}$/.test(artifact.sha256)) {
+      throw new SmartVMError(
+        `Hosted base image manifest ${label} artifact sha256 must be a 64 character hex string`,
+        'INVALID_BASE_IMAGE_MANIFEST',
+      );
+    }
+    if (
+      artifact.sizeBytes !== undefined &&
+      (!Number.isInteger(artifact.sizeBytes) || artifact.sizeBytes < 0)
+    ) {
+      throw new SmartVMError(
+        `Hosted base image manifest ${label} artifact sizeBytes must be a non-negative integer`,
+        'INVALID_BASE_IMAGE_MANIFEST',
+      );
+    }
+  }
+
+  private validateArtifactFileName(fileName: string, label: string): void {
+    if (
+      !fileName ||
+      fileName === '.' ||
+      fileName === '..' ||
+      fileName !== plugins.path.basename(fileName) ||
+      !/^[a-zA-Z0-9._-]+$/.test(fileName)
+    ) {
+      throw new SmartVMError(
+        `Hosted base image manifest ${label} artifact fileName must be a plain file name using letters, numbers, dot, underscore, and dash`,
+        'INVALID_BASE_IMAGE_MANIFEST',
+      );
+    }
+  }
+
+  private getArtifactSource(artifact: { url?: string; path?: string }, label: string): string {
+    if (!artifact.url && !artifact.path) {
+      throw new SmartVMError(
+        `Hosted base image manifest ${label} artifact requires url or path`,
+        'INVALID_BASE_IMAGE_MANIFEST',
+      );
+    }
+    if (artifact.url && artifact.path) {
+      throw new SmartVMError(
+        `Hosted base image manifest ${label} artifact must not set both url and path`,
+        'INVALID_BASE_IMAGE_MANIFEST',
+      );
+    }
+    return artifact.url || artifact.path!;
+  }
+
+  private getSourceFileName(source: string, fallback: string): string {
+    let fileName: string;
+    try {
+      fileName = plugins.path.basename(new URL(source).pathname);
+    } catch {
+      fileName = plugins.path.basename(source);
+    }
+    return this.sanitizeFileName(fileName || fallback);
+  }
+
+  private resolveBundleFilePath(bundleDir: string, fileName: string): string {
+    const resolvedBundleDir = plugins.path.resolve(bundleDir);
+    const resolvedFilePath = plugins.path.resolve(resolvedBundleDir, this.sanitizeFileName(fileName));
+    if (!this.isPathInside(resolvedBundleDir, resolvedFilePath)) {
+      throw new SmartVMError(
+        `Resolved base image artifact path escapes bundle directory: ${fileName}`,
+        'INVALID_BASE_IMAGE_MANIFEST',
+      );
+    }
+    return resolvedFilePath;
+  }
+
+  private sanitizeFileName(fileName: string): string {
+    const sanitized = plugins.path.basename(fileName).replace(/[^a-zA-Z0-9._-]/g, '_');
+    if (!sanitized || sanitized === '.' || sanitized === '..') {
+      return 'artifact';
+    }
+    return sanitized;
+  }
+
+  private sanitizeBundleId(bundleId: string): string {
+    return bundleId.replace(/[^a-zA-Z0-9._-]/g, '_');
+  }
+
+  private async listCiKeys(ciVersion: string, arch: TFirecrackerArch): Promise<string[]> {
+    const prefix = `firecracker-ci/${ciVersion}/${arch}/`;
+    try {
+      const response = await plugins.SmartRequest.create()
+        .url(`${FIRECRACKER_CI_BUCKET_URL}/?prefix=${encodeURIComponent(prefix)}&list-type=2`)
+        .get();
+      const body = await response.text();
+      const keys = Array.from(body.matchAll(/<Key>([^<]+)<\/Key>/g)).map((match) => this.decodeXml(match[1]));
+      if (keys.length === 0) {
+        throw new Error(`No Firecracker CI artifacts found for ${ciVersion}/${arch}`);
+      }
+      return keys;
+    } catch (err) {
+      throw new SmartVMError(
+        `Failed to list Firecracker CI artifacts for ${ciVersion}/${arch}: ${getErrorMessage(err)}`,
+        'BASE_IMAGE_RESOLVE_FAILED',
+      );
+    }
+  }
+
+  private selectKernelKey(keys: string[]): string {
+    const kernelKeys = keys.filter((key) => /\/vmlinux-\d+\.\d+\.\d+$/.test(key) && !key.includes('/debug/'));
+    if (kernelKeys.length === 0) {
+      throw new SmartVMError('No suitable Firecracker CI kernel image found', 'BASE_IMAGE_RESOLVE_FAILED');
+    }
+    return kernelKeys.sort((a, b) => this.compareKernelKeys(a, b)).at(-1)!;
+  }
+
+  private selectRootfsKey(keys: string[]): string {
+    const squashfsKeys = keys.filter((key) => /\/ubuntu-[^/]+\.squashfs$/.test(key));
+    if (squashfsKeys.length > 0) {
+      return squashfsKeys.sort((a, b) => a.localeCompare(b, undefined, { numeric: true })).at(-1)!;
+    }
+    const ext4Keys = keys.filter((key) => /\/ubuntu-[^/]+\.ext4$/.test(key));
+    if (ext4Keys.length > 0) {
+      return ext4Keys.sort((a, b) => a.localeCompare(b, undefined, { numeric: true })).at(-1)!;
+    }
+    throw new SmartVMError('No suitable Firecracker CI rootfs image found', 'BASE_IMAGE_RESOLVE_FAILED');
+  }
+
+  private compareKernelKeys(a: string, b: string): number {
+    const aParts = this.extractKernelVersion(a);
+    const bParts = this.extractKernelVersion(b);
+    for (let i = 0; i < 3; i++) {
+      if (aParts[i] !== bParts[i]) {
+        return aParts[i] - bParts[i];
+      }
+    }
+    return a.localeCompare(b);
+  }
+
+  private extractKernelVersion(key: string): [number, number, number] {
+    const match = key.match(/vmlinux-(\d+)\.(\d+)\.(\d+)$/);
+    if (!match) {
+      return [0, 0, 0];
+    }
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+  }
+
+  private buildBundleId(
+    preset: TBaseImagePreset,
+    ciVersion: string,
+    arch: TFirecrackerArch,
+    kernelKey: string,
+    rootfsKey: string,
+  ): string {
+    const rawId = [
+      preset,
+      ciVersion,
+      arch,
+      plugins.path.basename(kernelKey),
+      plugins.path.basename(rootfsKey),
+    ].join('-');
+    return this.sanitizeBundleId(rawId);
+  }
+
+  private buildBootArgs(arch: TFirecrackerArch, rootfsType: TBaseImageRootfsType): string {
+    const args = ['console=ttyS0', 'reboot=k', 'panic=1', 'pci=off'];
+    if (arch === 'aarch64') {
+      args.unshift('keep_bootcon');
+    }
+    if (rootfsType === 'squashfs') {
+      args.push('ro', 'rootfstype=squashfs');
+    }
+    return args.join(' ');
+  }
+
+  private keyToUrl(key: string): string {
+    return `${FIRECRACKER_CI_BUCKET_URL}/${key}`;
+  }
+
+  private async prepareArtifact(options: {
+    url?: string;
+    sourcePath?: string;
+    targetPath: string;
+    expectedSha256?: string;
+    expectedBytes?: number;
+  }): Promise<void> {
+    if (options.sourcePath) {
+      await plugins.fs.promises.copyFile(options.sourcePath, options.targetPath);
+    } else if (options.url) {
+      await this.downloadFile(options.url, options.targetPath);
+    } else {
+      throw new Error('Artifact requires url or sourcePath');
+    }
+
+    const stat = await plugins.fs.promises.stat(options.targetPath);
+    if (options.expectedBytes !== undefined && stat.size !== options.expectedBytes) {
+      throw new Error(
+        `Artifact ${options.targetPath} size mismatch: expected ${options.expectedBytes}, got ${stat.size}`,
+      );
+    }
+    if (options.expectedSha256) {
+      const actualSha256 = await this.sha256File(options.targetPath);
+      if (actualSha256.toLowerCase() !== options.expectedSha256.toLowerCase()) {
+        throw new Error(
+          `Artifact ${options.targetPath} SHA256 mismatch: expected ${options.expectedSha256}, got ${actualSha256}`,
+        );
+      }
+    }
+  }
+
+  private async downloadFile(url: string, targetPath: string): Promise<TShellExecResult> {
+    await plugins.fs.promises.mkdir(plugins.path.dirname(targetPath), { recursive: true });
+    const tempPath = `${targetPath}.download`;
+    await plugins.fs.promises.rm(tempPath, { force: true });
+    const result = await this.shell.execSpawn('curl', ['-fSL', '-o', tempPath, url], { silent: true });
+    if (result.exitCode !== 0) {
+      const output = (result.stderr || result.stdout || '').trim();
+      throw new Error(`curl failed for ${url} with code ${result.exitCode}${output ? `: ${output}` : ''}`);
+    }
+    await plugins.fs.promises.rename(tempPath, targetPath);
+    return result;
+  }
+
+  private async sha256File(filePath: string): Promise<string> {
+    const hash = plugins.crypto.createHash('sha256');
+    const stream = plugins.fs.createReadStream(filePath);
+    for await (const chunk of stream) {
+      hash.update(chunk);
+    }
+    return hash.digest('hex');
+  }
+
+  private async readCompleteBundle(bundleDir: string): Promise<IBaseImageBundle | undefined> {
+    const manifestPath = this.getManifestPath(bundleDir);
+    try {
+      const bundle = {
+        ...await this.readBundleManifest(manifestPath),
+        bundleDir,
+      };
+      await this.verifyCachedBundle(bundle);
+      return bundle;
+    } catch {
+      return undefined;
+    }
+  }
+
+  private async verifyCachedBundle(bundle: IBaseImageBundle): Promise<void> {
+    if (!this.isPathInside(bundle.bundleDir, bundle.kernelImagePath)) {
+      throw new Error(`Cached kernel path escapes bundle directory: ${bundle.kernelImagePath}`);
+    }
+    if (!this.isPathInside(bundle.bundleDir, bundle.rootfsPath)) {
+      throw new Error(`Cached rootfs path escapes bundle directory: ${bundle.rootfsPath}`);
+    }
+    if (!bundle.checksums?.kernelSha256 || !bundle.checksums?.rootfsSha256) {
+      throw new Error(`Cached bundle ${bundle.bundleId} is missing checksums`);
+    }
+    if (bundle.sizes?.kernelBytes === undefined || bundle.sizes.rootfsBytes === undefined) {
+      throw new Error(`Cached bundle ${bundle.bundleId} is missing sizes`);
+    }
+
+    const [kernelStat, rootfsStat] = await Promise.all([
+      plugins.fs.promises.stat(bundle.kernelImagePath),
+      plugins.fs.promises.stat(bundle.rootfsPath),
+    ]);
+    if (kernelStat.size !== bundle.sizes.kernelBytes) {
+      throw new Error(`Cached kernel size mismatch for bundle ${bundle.bundleId}`);
+    }
+    if (rootfsStat.size !== bundle.sizes.rootfsBytes) {
+      throw new Error(`Cached rootfs size mismatch for bundle ${bundle.bundleId}`);
+    }
+
+    const [kernelSha256, rootfsSha256] = await Promise.all([
+      this.sha256File(bundle.kernelImagePath),
+      this.sha256File(bundle.rootfsPath),
+    ]);
+    if (kernelSha256.toLowerCase() !== bundle.checksums.kernelSha256.toLowerCase()) {
+      throw new Error(`Cached kernel SHA256 mismatch for bundle ${bundle.bundleId}`);
+    }
+    if (rootfsSha256.toLowerCase() !== bundle.checksums.rootfsSha256.toLowerCase()) {
+      throw new Error(`Cached rootfs SHA256 mismatch for bundle ${bundle.bundleId}`);
+    }
+  }
+
+  private isPathInside(baseDir: string, candidatePath: string): boolean {
+    const resolvedBase = plugins.path.resolve(baseDir);
+    const resolvedCandidate = plugins.path.resolve(candidatePath);
+    return resolvedCandidate === resolvedBase || resolvedCandidate.startsWith(`${resolvedBase}${plugins.path.sep}`);
+  }
+
+  private getManifestPath(bundleDir: string): string {
+    return plugins.path.join(bundleDir, 'manifest.json');
+  }
+
+  private async readBundleManifest(manifestPath: string): Promise<IBaseImageBundle> {
+    const raw = await plugins.fs.promises.readFile(manifestPath, 'utf8');
+    return JSON.parse(raw) as IBaseImageBundle;
+  }
+
+  private async writeBundleManifest(bundle: IBaseImageBundle): Promise<void> {
+    await plugins.fs.promises.mkdir(bundle.bundleDir, { recursive: true });
+    await plugins.fs.promises.writeFile(
+      this.getManifestPath(bundle.bundleDir),
+      `${JSON.stringify(bundle, null, 2)}\n`,
+    );
+  }
+
+  private async listCachedBundles(): Promise<IBaseImageBundle[]> {
+    let entries: string[];
+    try {
+      entries = await plugins.fs.promises.readdir(this.cacheDir);
+    } catch {
+      return [];
+    }
+
+    const bundles: IBaseImageBundle[] = [];
+    for (const entry of entries) {
+      const bundleDir = plugins.path.join(this.cacheDir, entry);
+      try {
+        const stat = await plugins.fs.promises.stat(bundleDir);
+        if (!stat.isDirectory()) {
+          continue;
+        }
+        const bundle = await this.readBundleManifest(this.getManifestPath(bundleDir));
+        bundles.push({
+          ...bundle,
+          bundleDir,
+        });
+      } catch {
+        // Ignore incomplete cache entries.
+      }
+    }
+    return bundles;
+  }
+
+  private decodeXml(value: string): string {
+    return value
+      .replace(/&amp;/g, '&')
+      .replace(/&lt;/g, '<')
+      .replace(/&gt;/g, '>')
+      .replace(/&quot;/g, '"')
+      .replace(/&#39;/g, "'");
+  }
+}

ts/classes.firecrackerprocess.ts

@@ -3,14 +3,23 @@ import type { IFirecrackerProcessOptions } from './interfaces/index.js';
 import { SmartVMError } from './interfaces/index.js';
 import { SocketClient } from './classes.socketclient.js';
 
+type TStreamingResult = Awaited<ReturnType<InstanceType<typeof plugins.smartshell.Smartshell>['execSpawnStreaming']>>;
+type TExecResult = Awaited<TStreamingResult['finalPromise']>;
+
+function getErrorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
 /**
  * Manages a single Firecracker child process, including startup, readiness polling, and shutdown.
  */
 export class FirecrackerProcess {
   private options: IFirecrackerProcessOptions;
-  private streaming: any | null = null;
+  private streaming: TStreamingResult | null = null;
   private shell: InstanceType<typeof plugins.smartshell.Smartshell>;
   private smartExitInstance: InstanceType<typeof plugins.smartexit.SmartExit> | null = null;
+  private lastExitResult: TExecResult | null = null;
+  private lastExitError: string | null = null;
   public socketClient: SocketClient;
 
   constructor(options: IFirecrackerProcessOptions) {
@@ -28,14 +37,21 @@ export class FirecrackerProcess {
       plugins.fs.unlinkSync(this.options.socketPath);
     }
 
-    // Build the command
-    let cmd = `${this.options.binaryPath} --api-sock ${this.options.socketPath}`;
+    // Build the command args without a shell so paths are not interpreted.
+    const args = ['--api-sock', this.options.socketPath];
     if (this.options.logLevel) {
-      cmd += ` --level ${this.options.logLevel}`;
+      args.push('--level', this.options.logLevel);
     }
 
     // Spawn the process
-    this.streaming = await this.shell.execStreaming(cmd, true);
+    this.streaming = await this.shell.execSpawnStreaming(this.options.binaryPath, args, { silent: true });
+    this.streaming.finalPromise
+      .then((result) => {
+        this.lastExitResult = result;
+      })
+      .catch((err) => {
+        this.lastExitError = getErrorMessage(err);
+      });
 
     // Register with smartexit for automatic cleanup
     if (this.streaming?.childProcess) {
@@ -46,9 +62,11 @@ export class FirecrackerProcess {
     // Wait for the socket file to appear
     const socketReady = await this.waitForSocket(10000);
     if (!socketReady) {
+      const wasRunning = this.isRunning();
+      const diagnostics = this.formatDiagnostics();
       await this.stop();
       throw new SmartVMError(
-        'Firecracker socket did not become ready within timeout',
+        `Firecracker socket did not become ready within timeout${diagnostics || (wasRunning ? '' : this.formatDiagnostics())}`,
         'SOCKET_TIMEOUT',
       );
     }
@@ -56,9 +74,10 @@ export class FirecrackerProcess {
     // Wait for the API to be responsive
     const apiReady = await this.socketClient.isReady(5000);
     if (!apiReady) {
+      const diagnostics = this.formatDiagnostics();
       await this.stop();
       throw new SmartVMError(
-        'Firecracker API did not become responsive within timeout',
+        `Firecracker API did not become responsive within timeout${diagnostics}`,
         'API_TIMEOUT',
       );
     }
@@ -73,36 +92,69 @@ export class FirecrackerProcess {
       if (plugins.fs.existsSync(this.options.socketPath)) {
         return true;
       }
+      if (this.streaming && !this.isRunning()) {
+        return false;
+      }
       await plugins.smartdelay.delayFor(100);
     }
     return false;
   }
 
+  private async waitForExit(streaming: TStreamingResult, timeoutMs: number): Promise<boolean> {
+    return Promise.race([
+      streaming.finalPromise.then((result) => {
+        this.lastExitResult = result;
+        return true;
+      }).catch((err) => {
+        this.lastExitError = getErrorMessage(err);
+        return true;
+      }),
+      plugins.smartdelay.delayFor(timeoutMs).then(() => false),
+    ]);
+  }
+
+  private formatDiagnostics(): string {
+    if (this.lastExitError) {
+      return `: ${this.lastExitError}`;
+    }
+    if (this.lastExitResult) {
+      const output = (this.lastExitResult.stderr || this.lastExitResult.stdout || '').trim();
+      return `: process exited with code ${this.lastExitResult.exitCode}${output ? `: ${output}` : ''}`;
+    }
+    return '';
+  }
+
   /**
    * Gracefully stop the Firecracker process with SIGTERM, then SIGKILL after timeout.
    */
   public async stop(): Promise<void> {
-    if (!this.streaming) return;
+    const streaming = this.streaming;
+    if (!streaming) return;
 
     try {
       // Try graceful termination first
-      await this.streaming.terminate();
+      await streaming.terminate();
 
       // Wait up to 5 seconds for the process to exit
-      const exitPromise = Promise.race([
-        this.streaming.finalPromise,
-        plugins.smartdelay.delayFor(5000),
-      ]);
-      await exitPromise;
+      const terminated = await this.waitForExit(streaming, 5000);
+      if (!terminated) {
+        await streaming.kill();
+        await this.waitForExit(streaming, 1000);
+      }
     } catch {
       // If termination fails, force kill
       try {
-        await this.streaming.kill();
+        await streaming.kill();
+        await this.waitForExit(streaming, 1000);
       } catch {
         // Process may already be dead
       }
     }
 
+    if (this.smartExitInstance) {
+      this.smartExitInstance.removeProcess(streaming.childProcess);
+      this.smartExitInstance = null;
+    }
     this.streaming = null;
   }
 
@@ -122,10 +174,11 @@ export class FirecrackerProcess {
    * Check if the process is currently running.
    */
   public isRunning(): boolean {
-    if (!this.streaming?.childProcess) return false;
+    const pid = this.streaming?.childProcess?.pid;
+    if (!pid) return false;
     try {
       // Sending signal 0 tests if process exists without actually sending a signal
-      process.kill(this.streaming.childProcess.pid, 0);
+      process.kill(pid, 0);
       return true;
     } catch {
       return false;

ts/classes.imagemanager.ts

@@ -2,6 +2,12 @@ import * as plugins from './plugins.js';
 import type { TFirecrackerArch } from './interfaces/index.js';
 import { SmartVMError } from './interfaces/index.js';
 
+type TShellExecResult = Awaited<ReturnType<InstanceType<typeof plugins.smartshell.Smartshell>['execSpawn']>>;
+
+function getErrorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
 /**
  * Helper to check if a file or directory exists.
  */
@@ -21,10 +27,21 @@ async function pathExists(filePath: string): Promise<boolean> {
 export class ImageManager {
   private dataDir: string;
   private arch: TFirecrackerArch;
+  private shell: InstanceType<typeof plugins.smartshell.Smartshell>;
 
   constructor(dataDir: string, arch: TFirecrackerArch = 'x86_64') {
     this.dataDir = dataDir;
     this.arch = arch;
+    this.shell = new plugins.smartshell.Smartshell({ executor: 'bash' });
+  }
+
+  private async runChecked(command: string, args: string[]): Promise<TShellExecResult> {
+    const result = await this.shell.execSpawn(command, args, { silent: true });
+    if (result.exitCode !== 0) {
+      const output = (result.stderr || result.stdout || '').trim();
+      throw new Error(`${command} ${args.join(' ')} exited with code ${result.exitCode}${output ? `: ${output}` : ''}`);
+    }
+    return result;
   }
 
   /**
@@ -89,14 +106,22 @@ export class ImageManager {
    */
   public async getLatestVersion(): Promise<string> {
     try {
-      const response = await plugins.SmartRequest.create()
-        .url('https://api.github.com/repos/firecracker-microvm/firecracker/releases/latest')
-        .get();
-      const data = await response.json() as { tag_name: string };
-      return data.tag_name;
+      const result = await this.runChecked('curl', [
+        '-fsSLI',
+        '-o',
+        '/dev/null',
+        '-w',
+        '%{url_effective}',
+        'https://github.com/firecracker-microvm/firecracker/releases/latest',
+      ]);
+      const match = result.stdout.trim().match(/\/releases\/tag\/(v\d+\.\d+\.\d+)$/);
+      if (!match) {
+        throw new Error(`Could not parse latest Firecracker release URL: ${result.stdout.trim()}`);
+      }
+      return match[1];
     } catch (err) {
       throw new SmartVMError(
-        `Failed to fetch latest Firecracker version: ${(err as Error).message}`,
+        `Failed to fetch latest Firecracker version: ${getErrorMessage(err)}`,
         'VERSION_FETCH_FAILED',
       );
     }
@@ -119,11 +144,10 @@ export class ImageManager {
 
     try {
       // Download the archive
-      const shell = new plugins.smartshell.Smartshell({ executor: 'bash' });
-      await shell.exec(`curl -fSL -o "${archivePath}" "${downloadUrl}"`);
+      await this.runChecked('curl', ['-fSL', '-o', archivePath, downloadUrl]);
 
       // Extract the archive
-      await shell.exec(`tar -xzf "${archivePath}" -C "${targetDir}"`);
+      await this.runChecked('tar', ['-xzf', archivePath, '-C', targetDir]);
 
       // Firecracker archives contain a directory like release-v1.5.0-x86_64/
       // with binaries named like firecracker-v1.5.0-x86_64
@@ -134,21 +158,25 @@ export class ImageManager {
       const jailerDst = this.getJailerPath(version);
 
       // Move binaries to expected paths
-      await shell.exec(`mv "${firecrackerSrc}" "${firecrackerDst}"`);
+      await plugins.fs.promises.rename(firecrackerSrc, firecrackerDst);
       if (await pathExists(jailerSrc)) {
-        await shell.exec(`mv "${jailerSrc}" "${jailerDst}"`);
+        await plugins.fs.promises.rename(jailerSrc, jailerDst);
       }
 
       // Make executable
-      await shell.exec(`chmod +x "${firecrackerDst}"`);
+      await plugins.fs.promises.chmod(firecrackerDst, 0o755);
+      if (await pathExists(jailerDst)) {
+        await plugins.fs.promises.chmod(jailerDst, 0o755);
+      }
 
       // Clean up
-      await shell.exec(`rm -rf "${archivePath}" "${extractedDir}"`);
+      await plugins.fs.promises.rm(archivePath, { force: true });
+      await plugins.fs.promises.rm(extractedDir, { recursive: true, force: true });
 
       return firecrackerDst;
     } catch (err) {
       throw new SmartVMError(
-        `Failed to download Firecracker ${version}: ${(err as Error).message}`,
+        `Failed to download Firecracker ${version}: ${getErrorMessage(err)}`,
         'DOWNLOAD_FAILED',
       );
     }
@@ -163,12 +191,11 @@ export class ImageManager {
     const kernelPath = plugins.path.join(kernelsDir, name);
 
     try {
-      const shell = new plugins.smartshell.Smartshell({ executor: 'bash' });
-      await shell.exec(`curl -fSL -o "${kernelPath}" "${url}"`);
+      await this.runChecked('curl', ['-fSL', '-o', kernelPath, url]);
       return kernelPath;
     } catch (err) {
       throw new SmartVMError(
-        `Failed to download kernel from ${url}: ${(err as Error).message}`,
+        `Failed to download kernel from ${url}: ${getErrorMessage(err)}`,
         'DOWNLOAD_FAILED',
       );
     }
@@ -183,12 +210,11 @@ export class ImageManager {
     const rootfsPath = plugins.path.join(rootfsDir, name);
 
     try {
-      const shell = new plugins.smartshell.Smartshell({ executor: 'bash' });
-      await shell.exec(`curl -fSL -o "${rootfsPath}" "${url}"`);
+      await this.runChecked('curl', ['-fSL', '-o', rootfsPath, url]);
       return rootfsPath;
     } catch (err) {
       throw new SmartVMError(
-        `Failed to download rootfs from ${url}: ${(err as Error).message}`,
+        `Failed to download rootfs from ${url}: ${getErrorMessage(err)}`,
         'DOWNLOAD_FAILED',
       );
     }
@@ -203,13 +229,12 @@ export class ImageManager {
     const rootfsPath = plugins.path.join(rootfsDir, name);
 
     try {
-      const shell = new plugins.smartshell.Smartshell({ executor: 'bash' });
-      await shell.exec(`dd if=/dev/zero of="${rootfsPath}" bs=1M count=${sizeMib}`);
-      await shell.exec(`mkfs.ext4 "${rootfsPath}"`);
+      await this.runChecked('dd', ['if=/dev/zero', `of=${rootfsPath}`, 'bs=1M', `count=${sizeMib}`]);
+      await this.runChecked('mkfs.ext4', [rootfsPath]);
       return rootfsPath;
     } catch (err) {
       throw new SmartVMError(
-        `Failed to create blank rootfs: ${(err as Error).message}`,
+        `Failed to create blank rootfs: ${getErrorMessage(err)}`,
         'ROOTFS_CREATE_FAILED',
       );
     }
@@ -224,12 +249,11 @@ export class ImageManager {
     const targetPath = plugins.path.join(rootfsDir, targetName);
 
     try {
-      const shell = new plugins.smartshell.Smartshell({ executor: 'bash' });
-      await shell.exec(`cp "${sourcePath}" "${targetPath}"`);
+      await plugins.fs.promises.copyFile(sourcePath, targetPath);
       return targetPath;
     } catch (err) {
       throw new SmartVMError(
-        `Failed to clone rootfs: ${(err as Error).message}`,
+        `Failed to clone rootfs: ${getErrorMessage(err)}`,
         'ROOTFS_CLONE_FAILED',
       );
     }

ts/classes.microvm.ts

@@ -2,8 +2,10 @@ import * as plugins from './plugins.js';
 import type {
   TVMState,
   IMicroVMConfig,
+  IMicroVMRuntimeOptions,
   ISnapshotCreateParams,
   ISnapshotLoadParams,
+  IDriveConfig,
   ITapDevice,
 } from './interfaces/index.js';
 import { SmartVMError } from './interfaces/index.js';
@@ -26,6 +28,9 @@ export class MicroVM {
   private networkManager: NetworkManager;
   private binaryPath: string;
   private socketPath: string;
+  private runtimeDir: string;
+  private ephemeralWritableDrives: boolean;
+  private vmRuntimeDir: string | null = null;
   private tapDevices: ITapDevice[] = [];
 
   constructor(
@@ -34,12 +39,15 @@ export class MicroVM {
     binaryPath: string,
     socketPath: string,
     networkManager: NetworkManager,
+    runtimeOptions: IMicroVMRuntimeOptions = {},
   ) {
     this.id = id;
     this.vmConfig = new VMConfig(config);
     this.binaryPath = binaryPath;
     this.socketPath = socketPath;
     this.networkManager = networkManager;
+    this.runtimeDir = runtimeOptions.runtimeDir || plugins.path.join(plugins.os.tmpdir(), '.smartvm', 'runtime');
+    this.ephemeralWritableDrives = runtimeOptions.ephemeralWritableDrives ?? true;
   }
 
   /**
@@ -54,6 +62,16 @@ export class MicroVM {
     }
   }
 
+  private getSocketClient(operation: string): SocketClient {
+    if (!this.socketClient) {
+      throw new SmartVMError(
+        `Cannot ${operation}: socket client not initialized`,
+        'NO_CLIENT',
+      );
+    }
+    return this.socketClient;
+  }
+
   /**
    * Start the MicroVM.
    * Validates config, starts the Firecracker process, applies pre-boot configuration, and boots the VM.
@@ -73,6 +91,9 @@ export class MicroVM {
     this.state = 'configuring';
 
     try {
+      await this.ensureVMRuntimeDir();
+      await this.prepareEphemeralDrives();
+
       // Start the Firecracker process
       this.process = new FirecrackerProcess({
         binaryPath: this.binaryPath,
@@ -244,7 +265,7 @@ export class MicroVM {
    */
   public async getMetadata(): Promise<any> {
     this.assertState(['running', 'paused'], 'getMetadata');
-    const response = await this.socketClient!.get('/mmds');
+    const response = await this.getSocketClient('getMetadata').get('/mmds');
     return response.body;
   }
 
@@ -282,7 +303,7 @@ export class MicroVM {
    * Get VM instance info.
    */
   public async getInfo(): Promise<any> {
-    const response = await this.socketClient!.get('/');
+    const response = await this.getSocketClient('getInfo').get('/');
     return response.body;
   }
 
@@ -290,7 +311,7 @@ export class MicroVM {
    * Get Firecracker version info.
    */
   public async getVersion(): Promise<any> {
-    const response = await this.socketClient!.get('/version');
+    const response = await this.getSocketClient('getVersion').get('/version');
     return response.body;
   }
 
@@ -308,6 +329,13 @@ export class MicroVM {
     return this.vmConfig;
   }
 
+  /**
+   * Get the per-VM runtime directory if it has been created.
+   */
+  public getRuntimeDir(): string | null {
+    return this.vmRuntimeDir;
+  }
+
   /**
    * Full cleanup: stop process, remove socket, remove TAP devices.
    */
@@ -324,20 +352,74 @@ export class MicroVM {
     }
     this.tapDevices = [];
 
+    if (this.vmRuntimeDir) {
+      await plugins.fs.promises.rm(this.vmRuntimeDir, { recursive: true, force: true });
+      this.vmRuntimeDir = null;
+    }
+
     this.socketClient = null;
     if (this.state !== 'error') {
       this.state = 'stopped';
     }
   }
 
+  private shouldStageDrive(drive: IDriveConfig): boolean {
+    if (!this.ephemeralWritableDrives) {
+      return false;
+    }
+    if (drive.ephemeral === false) {
+      return false;
+    }
+    if (drive.isReadOnly === true && drive.ephemeral !== true) {
+      return false;
+    }
+    return true;
+  }
+
+  private async ensureVMRuntimeDir(): Promise<string> {
+    if (!this.vmRuntimeDir) {
+      this.vmRuntimeDir = plugins.path.join(this.runtimeDir, this.sanitizePathPart(this.id));
+    }
+    await plugins.fs.promises.mkdir(this.vmRuntimeDir, { recursive: true });
+    return this.vmRuntimeDir;
+  }
+
+  private async prepareEphemeralDrives(): Promise<void> {
+    const drives = this.vmConfig.config.drives || [];
+    for (const drive of drives) {
+      if (!this.shouldStageDrive(drive)) {
+        continue;
+      }
+
+      const vmRuntimeDir = await this.ensureVMRuntimeDir();
+      const drivesDir = plugins.path.join(vmRuntimeDir, 'drives');
+      await plugins.fs.promises.mkdir(drivesDir, { recursive: true });
+
+      const sourcePath = drive.pathOnHost;
+      const sourceFileName = plugins.path.basename(sourcePath) || 'drive.img';
+      const stagedPath = plugins.path.join(
+        drivesDir,
+        `${this.sanitizePathPart(drive.driveId)}-${this.sanitizePathPart(sourceFileName)}`,
+      );
+
+      await plugins.fs.promises.copyFile(sourcePath, stagedPath);
+      drive.pathOnHost = stagedPath;
+    }
+  }
+
+  private sanitizePathPart(value: string): string {
+    const sanitized = value.replace(/[^a-zA-Z0-9._-]/g, '_');
+    if (!sanitized || sanitized === '.' || sanitized === '..') {
+      return 'item';
+    }
+    return sanitized;
+  }
+
   /**
    * Helper: PUT request with error handling.
    */
   private async apiPut(path: string, body: Record<string, any>): Promise<void> {
-    if (!this.socketClient) {
-      throw new SmartVMError('Socket client not initialized', 'NO_CLIENT');
-    }
-    const response = await this.socketClient.put(path, body);
+    const response = await this.getSocketClient(`PUT ${path}`).put(path, body);
     if (!response.ok) {
       throw new SmartVMError(
         `API PUT ${path} failed with status ${response.statusCode}: ${JSON.stringify(response.body)}`,
@@ -352,10 +434,7 @@ export class MicroVM {
    * Helper: PATCH request with error handling.
    */
   private async apiPatch(path: string, body: Record<string, any>): Promise<void> {
-    if (!this.socketClient) {
-      throw new SmartVMError('Socket client not initialized', 'NO_CLIENT');
-    }
-    const response = await this.socketClient.patch(path, body);
+    const response = await this.getSocketClient(`PATCH ${path}`).patch(path, body);
     if (!response.ok) {
       throw new SmartVMError(
         `API PATCH ${path} failed with status ${response.statusCode}: ${JSON.stringify(response.body)}`,

ts/classes.networkmanager.ts

@@ -1,7 +1,35 @@
 import * as plugins from './plugins.js';
-import type { INetworkManagerOptions, ITapDevice } from './interfaces/index.js';
+import type {
+  IFirewallConfig,
+  IFirewallRule,
+  INetworkManagerOptions,
+  ITapDevice,
+  TFirewallAction,
+  TFirewallProtocol,
+  TWireGuardConfig,
+} from './interfaces/index.js';
 import { SmartVMError } from './interfaces/index.js';
 
+type TShellExecResult = Awaited<ReturnType<InstanceType<typeof plugins.smartshell.Smartshell>['execSpawn']>>;
+
+interface IParsedSubnet {
+  networkAddress: number;
+  broadcastAddress: number;
+  cidr: number;
+  subnetMask: string;
+}
+
+interface IParsedWireGuardConfig {
+  setConfig: string;
+  addresses: string[];
+  mtu?: number;
+}
+
+const FIREWALL_ACTION_TO_IPTABLES_TARGET: Record<TFirewallAction, 'ACCEPT' | 'DROP'> = {
+  allow: 'ACCEPT',
+  deny: 'DROP',
+};
+
 /**
  * Manages host networking for Firecracker VMs.
  * Creates TAP devices, Linux bridges, and configures NAT for VM internet access.
@@ -12,53 +40,430 @@ export class NetworkManager {
   private subnetCidr: number;
   private gatewayIp: string;
   private subnetMask: string;
-  private nextIpOctet: number;
+  private nextIpAddress: number;
+  private lastUsableIpAddress: number;
   private activeTaps: Map<string, ITapDevice> = new Map();
   private bridgeCreated: boolean = false;
+  private defaultRouteInterface: string | null = null;
+  private firewall?: IFirewallConfig;
+  private firewallChainName: string;
+  private firewallConfigured: boolean = false;
+  private wireguard?: TWireGuardConfig;
+  private wireGuardInterface: string | null = null;
+  private wireGuardManaged: boolean = false;
+  private wireGuardRouteConfigured: boolean = false;
+  private wireGuardRouteAdded: boolean = false;
+  private wireGuardIpRuleAdded: boolean = false;
+  private wireGuardRouteTable: number | null = null;
+  private natInterface: string | null = null;
+  private natConfigured: boolean = false;
+  private natRuleAdded: boolean = false;
   private shell: InstanceType<typeof plugins.smartshell.Smartshell>;
 
   constructor(options: INetworkManagerOptions = {}) {
     this.bridgeName = options.bridgeName || 'svbr0';
+    this.validateInterfaceName(this.bridgeName, 'bridgeName');
     const subnet = options.subnet || '172.30.0.0/24';
+    const parsedSubnet = this.parseSubnet(subnet);
 
-    // Parse the subnet
-    const [baseIp, cidrStr] = subnet.split('/');
-    this.subnetBase = baseIp;
-    this.subnetCidr = parseInt(cidrStr, 10);
-    this.subnetMask = this.cidrToSubnetMask(this.subnetCidr);
-
-    // Gateway is .1 in the subnet
-    const parts = this.subnetBase.split('.').map(Number);
-    parts[3] = 1;
-    this.gatewayIp = parts.join('.');
-
-    // VMs start at .2
-    this.nextIpOctet = 2;
+    this.subnetBase = this.intToIp(parsedSubnet.networkAddress);
+    this.subnetCidr = parsedSubnet.cidr;
+    this.subnetMask = parsedSubnet.subnetMask;
+    this.gatewayIp = this.intToIp(parsedSubnet.networkAddress + 1);
+    this.nextIpAddress = parsedSubnet.networkAddress + 2;
+    this.lastUsableIpAddress = parsedSubnet.broadcastAddress - 1;
+    this.firewall = options.firewall;
+    this.wireguard = options.wireguard;
+    this.firewallChainName = this.buildFirewallChainName(this.bridgeName, this.subnetBase, this.subnetCidr);
+    this.validateFirewallConfig(this.firewall);
+    this.validateWireGuardConfig(this.wireguard);
 
     this.shell = new plugins.smartshell.Smartshell({ executor: 'bash' });
   }
 
   /**
-   * Convert a CIDR prefix length to a dotted-decimal subnet mask.
+   * Parse an IPv4 CIDR subnet and ensure there is room for a gateway and guests.
    */
-  private cidrToSubnetMask(cidr: number): string {
-    const mask = (0xffffffff << (32 - cidr)) >>> 0;
+  private parseSubnet(subnet: string): IParsedSubnet {
+    const [ip, cidrText, extra] = subnet.split('/');
+    const cidr = Number(cidrText);
+    if (!ip || !cidrText || extra !== undefined || !Number.isInteger(cidr) || cidr < 1 || cidr > 30) {
+      throw new SmartVMError(
+        `Invalid subnet '${subnet}': expected IPv4 CIDR with prefix length 1-30`,
+        'INVALID_SUBNET',
+      );
+    }
+
+    const ipAddress = this.ipToInt(ip);
+    const mask = this.cidrToMask(cidr);
+    const networkAddress = (ipAddress & mask) >>> 0;
+    const hostCount = 2 ** (32 - cidr);
+    const broadcastAddress = networkAddress + hostCount - 1;
+    if (hostCount < 4) {
+      throw new SmartVMError(
+        `Invalid subnet '${subnet}': at least two usable host addresses are required`,
+        'INVALID_SUBNET',
+      );
+    }
+
+    return {
+      networkAddress,
+      broadcastAddress,
+      cidr,
+      subnetMask: this.intToIp(mask),
+    };
+  }
+
+  private ipToInt(ip: string): number {
+    const octets = ip.split('.');
+    if (octets.length !== 4) {
+      throw new SmartVMError(`Invalid IPv4 address '${ip}'`, 'INVALID_SUBNET');
+    }
+
+    if (octets.some((octet) => !/^[0-9]+$/.test(octet))) {
+      throw new SmartVMError(`Invalid IPv4 address '${ip}'`, 'INVALID_SUBNET');
+    }
+
+    const numbers = octets.map((octet) => Number(octet));
+    if (numbers.some((octet) => !Number.isInteger(octet) || octet < 0 || octet > 255)) {
+      throw new SmartVMError(`Invalid IPv4 address '${ip}'`, 'INVALID_SUBNET');
+    }
+
+    return (
+      numbers[0] * 256 ** 3 +
+      numbers[1] * 256 ** 2 +
+      numbers[2] * 256 +
+      numbers[3]
+    ) >>> 0;
+  }
+
+  private intToIp(address: number): string {
     return [
-      (mask >>> 24) & 0xff,
-      (mask >>> 16) & 0xff,
-      (mask >>> 8) & 0xff,
-      mask & 0xff,
+      Math.floor(address / 256 ** 3) % 256,
+      Math.floor(address / 256 ** 2) % 256,
+      Math.floor(address / 256) % 256,
+      address % 256,
     ].join('.');
   }
 
+  private cidrToMask(cidr: number): number {
+    return (0xffffffff << (32 - cidr)) >>> 0;
+  }
+
+  private validateInterfaceName(name: string, fieldName: string): void {
+    if (typeof name !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,14}$/.test(name)) {
+      throw new SmartVMError(
+        `${fieldName} '${name}' is not a valid Linux interface name`,
+        'INVALID_INTERFACE_NAME',
+      );
+    }
+  }
+
+  private buildFirewallChainName(bridgeName: string, subnetBase: string, subnetCidr: number): string {
+    const hash = plugins.crypto
+      .createHash('sha256')
+      .update(`${bridgeName}:${subnetBase}/${subnetCidr}`)
+      .digest('hex')
+      .slice(0, 10);
+    return `SVMEG-${hash}`;
+  }
+
+  private getSubnetCidr(): string {
+    return `${this.subnetBase}/${this.subnetCidr}`;
+  }
+
+  private validateIpv4Cidr(value: string, fieldName: string, errorCode = 'INVALID_FIREWALL_CONFIG'): void {
+    const [ip, cidrText, extra] = value.split('/');
+    const cidr = cidrText === undefined || cidrText === '' ? 32 : Number(cidrText);
+    if (!ip || extra !== undefined || !Number.isInteger(cidr) || cidr < 0 || cidr > 32) {
+      throw new SmartVMError(
+        `${fieldName} '${value}' must be an IPv4 address or CIDR with prefix length 0-32`,
+        errorCode,
+      );
+    }
+    try {
+      this.ipToInt(ip);
+    } catch (err) {
+      if (err instanceof SmartVMError) {
+        throw new SmartVMError(
+          `${fieldName} '${value}' must be an IPv4 address or CIDR with prefix length 0-32`,
+          errorCode,
+        );
+      }
+      throw err;
+    }
+  }
+
+  private normalizeCidr(value: string): string {
+    return value.includes('/') ? value : `${value}/32`;
+  }
+
+  private validateFirewallConfig(firewall?: IFirewallConfig): void {
+    if (!firewall || firewall.egress === undefined) {
+      return;
+    }
+
+    const egress = firewall.egress;
+
+    if (!egress || typeof egress !== 'object') {
+      throw new SmartVMError('Firewall egress config must be an object', 'INVALID_FIREWALL_CONFIG');
+    }
+
+    if (
+      egress.defaultAction !== undefined &&
+      egress.defaultAction !== 'allow' &&
+      egress.defaultAction !== 'deny'
+    ) {
+      throw new SmartVMError(
+        `Invalid firewall egress defaultAction '${egress.defaultAction}'`,
+        'INVALID_FIREWALL_CONFIG',
+      );
+    }
+
+    if (egress.rules !== undefined && !Array.isArray(egress.rules)) {
+      throw new SmartVMError('Firewall egress rules must be an array', 'INVALID_FIREWALL_CONFIG');
+    }
+
+    for (const rule of egress.rules || []) {
+      this.validateFirewallRule(rule);
+    }
+  }
+
+  private validateFirewallRule(rule: IFirewallRule): void {
+    if (!rule || typeof rule !== 'object') {
+      throw new SmartVMError('Firewall rule must be an object', 'INVALID_FIREWALL_CONFIG');
+    }
+
+    if (rule.action !== 'allow' && rule.action !== 'deny') {
+      throw new SmartVMError(
+        `Invalid firewall rule action '${rule.action}'`,
+        'INVALID_FIREWALL_CONFIG',
+      );
+    }
+
+    const protocol = rule.protocol || 'all';
+    if (!['all', 'tcp', 'udp', 'icmp'].includes(protocol)) {
+      throw new SmartVMError(
+        `Invalid firewall rule protocol '${protocol}'`,
+        'INVALID_FIREWALL_CONFIG',
+      );
+    }
+
+    if (rule.to !== undefined) {
+      if (typeof rule.to !== 'string') {
+        throw new SmartVMError('Firewall rule destination must be a string', 'INVALID_FIREWALL_CONFIG');
+      }
+      this.validateIpv4Cidr(rule.to, 'firewall rule destination');
+    }
+
+    if (rule.comment !== undefined && typeof rule.comment !== 'string') {
+      throw new SmartVMError('Firewall rule comment must be a string', 'INVALID_FIREWALL_CONFIG');
+    }
+
+    const ports = this.normalizePorts(rule.ports);
+    if (ports.length > 0 && protocol !== 'tcp' && protocol !== 'udp') {
+      throw new SmartVMError(
+        'Firewall rule ports require protocol tcp or udp',
+        'INVALID_FIREWALL_CONFIG',
+      );
+    }
+  }
+
+  private normalizePorts(ports?: number | number[]): number[] {
+    if (ports === undefined) {
+      return [];
+    }
+    const portList = Array.isArray(ports) ? ports : [ports];
+    if (portList.length === 0) {
+      throw new SmartVMError('Firewall rule ports must not be empty', 'INVALID_FIREWALL_CONFIG');
+    }
+    for (const port of portList) {
+      if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new SmartVMError(
+          `Firewall rule port '${port}' must be an integer between 1 and 65535`,
+          'INVALID_FIREWALL_CONFIG',
+        );
+      }
+    }
+    return portList;
+  }
+
+  private validateWireGuardConfig(wireguard?: TWireGuardConfig): void {
+    if (!wireguard) {
+      return;
+    }
+
+    const routeTable = wireguard.routeTable === undefined ? 51820 : wireguard.routeTable;
+    if (!Number.isInteger(routeTable) || routeTable < 1 || routeTable > 4294967295) {
+      throw new SmartVMError(
+        `WireGuard routeTable '${routeTable}' must be an integer between 1 and 4294967295`,
+        'INVALID_WIREGUARD_CONFIG',
+      );
+    }
+
+    const wireguardOptions = wireguard as unknown as Record<string, unknown>;
+    const hasExistingInterface = Object.prototype.hasOwnProperty.call(wireguardOptions, 'existingInterface');
+    const hasManagedConfig = Object.prototype.hasOwnProperty.call(wireguardOptions, 'config');
+    if (hasExistingInterface && hasManagedConfig) {
+      throw new SmartVMError(
+        'WireGuard config must use either existingInterface or managed config, not both',
+        'INVALID_WIREGUARD_CONFIG',
+      );
+    }
+
+    if (hasExistingInterface) {
+      this.validateInterfaceName(wireguardOptions.existingInterface as string, 'wireguard.existingInterface');
+      return;
+    }
+
+    if (typeof wireguardOptions.config !== 'string') {
+      throw new SmartVMError('WireGuard managed config requires config text', 'INVALID_WIREGUARD_CONFIG');
+    }
+
+    const interfaceName = wireguardOptions.interfaceName === undefined
+      ? 'svwg0'
+      : wireguardOptions.interfaceName;
+    this.validateInterfaceName(interfaceName as string, 'wireguard.interfaceName');
+    this.parseWireGuardConfig(wireguardOptions.config);
+  }
+
+  private parseWireGuardConfig(config: string): IParsedWireGuardConfig {
+    if (!config || !config.trim()) {
+      throw new SmartVMError('WireGuard config must not be empty', 'INVALID_WIREGUARD_CONFIG');
+    }
+
+    const unsafeFields = new Set(['preup', 'postup', 'predown', 'postdown', 'saveconfig']);
+    const ignoredFields = new Set(['address', 'dns', 'mtu', 'table']);
+    const wireGuardInterfaceFields = new Set(['privatekey', 'listenport', 'fwmark']);
+    const wireGuardPeerFields = new Set([
+      'publickey',
+      'presharedkey',
+      'allowedips',
+      'endpoint',
+      'persistentkeepalive',
+    ]);
+    const setConfigLines: string[] = [];
+    const addresses: string[] = [];
+    let mtu: number | undefined;
+    let currentSection: 'Interface' | 'Peer' | null = null;
+    let sawPrivateKey = false;
+
+    for (const rawLine of config.split(/\r?\n/)) {
+      const trimmedLine = rawLine.trim();
+      if (!trimmedLine || trimmedLine.startsWith('#') || trimmedLine.startsWith(';')) {
+        continue;
+      }
+
+      const lineWithoutComment = trimmedLine.replace(/\s+[;#].*$/, '').trim();
+      if (!lineWithoutComment) {
+        continue;
+      }
+
+      const sectionMatch = lineWithoutComment.match(/^\[(Interface|Peer)\]$/i);
+      if (sectionMatch) {
+        currentSection = sectionMatch[1].toLowerCase() === 'interface' ? 'Interface' : 'Peer';
+        setConfigLines.push(`[${currentSection}]`);
+        continue;
+      }
+
+      const keyValueMatch = lineWithoutComment.match(/^([^=]+?)\s*=\s*(.+)$/);
+      if (!keyValueMatch || !currentSection) {
+        throw new SmartVMError(
+          `Invalid WireGuard config line '${rawLine.trim()}'`,
+          'INVALID_WIREGUARD_CONFIG',
+        );
+      }
+
+      const key = keyValueMatch[1].trim();
+      const normalizedKey = key.toLowerCase();
+      const value = keyValueMatch[2].trim();
+      if (unsafeFields.has(normalizedKey)) {
+        throw new SmartVMError(
+          `WireGuard config field '${key}' is not allowed because it can execute commands or mutate host state`,
+          'INVALID_WIREGUARD_CONFIG',
+        );
+      }
+
+      if (currentSection === 'Interface' && normalizedKey === 'address') {
+        for (const address of value.split(',').map((item) => item.trim()).filter(Boolean)) {
+          this.validateIpv4Cidr(address, 'WireGuard Address', 'INVALID_WIREGUARD_CONFIG');
+          addresses.push(this.normalizeCidr(address));
+        }
+        continue;
+      }
+
+      if (currentSection === 'Interface' && normalizedKey === 'mtu') {
+        const parsedMtu = Number(value);
+        if (!Number.isInteger(parsedMtu) || parsedMtu < 576 || parsedMtu > 9000) {
+          throw new SmartVMError(
+            `WireGuard MTU '${value}' must be an integer between 576 and 9000`,
+            'INVALID_WIREGUARD_CONFIG',
+          );
+        }
+        mtu = parsedMtu;
+        continue;
+      }
+
+      if (currentSection === 'Peer' && normalizedKey === 'allowedips') {
+        const allowedIps = value.split(',').map((item) => item.trim()).filter(Boolean);
+        if (allowedIps.length === 0) {
+          throw new SmartVMError('WireGuard Peer.AllowedIPs must not be empty', 'INVALID_WIREGUARD_CONFIG');
+        }
+        for (const allowedIp of allowedIps) {
+          this.validateIpv4Cidr(allowedIp, 'WireGuard AllowedIPs', 'INVALID_WIREGUARD_CONFIG');
+        }
+        setConfigLines.push(`${key} = ${allowedIps.join(', ')}`);
+        continue;
+      }
+
+      if (ignoredFields.has(normalizedKey)) {
+        continue;
+      }
+
+      const allowedFields = currentSection === 'Interface'
+        ? wireGuardInterfaceFields
+        : wireGuardPeerFields;
+      if (!allowedFields.has(normalizedKey)) {
+        throw new SmartVMError(
+          `Unsupported WireGuard ${currentSection} field '${key}'`,
+          'INVALID_WIREGUARD_CONFIG',
+        );
+      }
+      if (currentSection === 'Interface' && normalizedKey === 'privatekey') {
+        sawPrivateKey = true;
+      }
+
+      setConfigLines.push(`${key} = ${value}`);
+    }
+
+    if (!sawPrivateKey) {
+      throw new SmartVMError('WireGuard config requires Interface.PrivateKey', 'INVALID_WIREGUARD_CONFIG');
+    }
+    if (addresses.length === 0) {
+      throw new SmartVMError('WireGuard config requires at least one IPv4 Interface.Address', 'INVALID_WIREGUARD_CONFIG');
+    }
+
+    return {
+      setConfig: `${setConfigLines.join('\n')}\n`,
+      addresses,
+      mtu,
+    };
+  }
+
   /**
    * Allocate the next available IP address in the subnet.
    */
   public allocateIp(): string {
-    const parts = this.subnetBase.split('.').map(Number);
-    parts[3] = this.nextIpOctet;
-    this.nextIpOctet++;
-    return parts.join('.');
+    if (this.nextIpAddress > this.lastUsableIpAddress) {
+      throw new SmartVMError(
+        `Subnet ${this.subnetBase}/${this.subnetCidr} has no available guest IP addresses`,
+        'IP_EXHAUSTED',
+      );
+    }
+
+    const ip = this.intToIp(this.nextIpAddress);
+    this.nextIpAddress++;
+    return ip;
   }
 
   /**
@@ -102,37 +507,320 @@ export class NetworkManager {
     return tapName.substring(0, 15);
   }
 
+  private async run(command: string, args: string[]): Promise<TShellExecResult> {
+    return this.shell.execSpawn(command, args, { silent: true });
+  }
+
+  private async runChecked(command: string, args: string[]): Promise<TShellExecResult> {
+    const result = await this.run(command, args);
+    if (result.exitCode !== 0) {
+      const output = (result.stderr || result.stdout || '').trim();
+      throw new Error(`${command} ${args.join(' ')} exited with code ${result.exitCode}${output ? `: ${output}` : ''}`);
+    }
+    return result;
+  }
+
+  private async getDefaultRouteInterface(): Promise<string> {
+    if (this.defaultRouteInterface) {
+      return this.defaultRouteInterface;
+    }
+
+    const result = await this.runChecked('ip', ['route', 'show', 'default']);
+    const match = result.stdout.match(/\bdev\s+([^\s]+)/);
+    if (!match) {
+      throw new Error('Could not determine default route interface');
+    }
+
+    const iface = match[1];
+    this.validateInterfaceName(iface, 'default route interface');
+    this.defaultRouteInterface = iface;
+    return iface;
+  }
+
+  private getSharedMemoryTempDir(): string {
+    try {
+      if (plugins.fs.existsSync('/dev/shm') && plugins.fs.statSync('/dev/shm').isDirectory()) {
+        return '/dev/shm';
+      }
+    } catch {
+      // Fall through to os.tmpdir().
+    }
+    return plugins.os.tmpdir();
+  }
+
+  private async configureWireGuardEgress(): Promise<string> {
+    if (!this.wireguard || this.wireguard.routeAllVmTraffic === false) {
+      return this.getDefaultRouteInterface();
+    }
+
+    try {
+      const iface = await this.ensureWireGuardInterface();
+      const routeTable = this.wireguard.routeTable === undefined ? 51820 : this.wireguard.routeTable;
+      this.wireGuardInterface = iface;
+      this.wireGuardRouteTable = routeTable;
+      this.wireGuardRouteAdded = false;
+      this.wireGuardIpRuleAdded = false;
+      const routeResult = await this.run('ip', ['route', 'show', 'table', String(routeTable), 'default']);
+      const existingDefaultRoutes = routeResult.stdout
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean);
+      if (existingDefaultRoutes.some((line) => !line.includes(` dev ${iface} `) && !line.endsWith(` dev ${iface}`))) {
+        throw new SmartVMError(
+          `WireGuard route table ${routeTable} already has a default route not using ${iface}`,
+          'WIREGUARD_SETUP_FAILED',
+        );
+      }
+      if (existingDefaultRoutes.length === 0) {
+        await this.runChecked('ip', [
+          'route',
+          'add',
+          'default',
+          'dev',
+          iface,
+          'table',
+          String(routeTable),
+        ]);
+        this.wireGuardRouteAdded = true;
+      }
+      this.wireGuardRouteConfigured = true;
+      if (!await this.hasWireGuardIpRule(routeTable)) {
+        await this.runChecked('ip', [
+          'rule',
+          'add',
+          'from',
+          this.getSubnetCidr(),
+          'table',
+          String(routeTable),
+        ]);
+        this.wireGuardIpRuleAdded = true;
+      }
+      return iface;
+    } catch (err) {
+      if (err instanceof SmartVMError) {
+        throw err;
+      }
+      const message = err instanceof Error ? err.message : String(err);
+      throw new SmartVMError(`Failed to configure WireGuard egress: ${message}`, 'WIREGUARD_SETUP_FAILED');
+    }
+  }
+
+  private async hasWireGuardIpRule(routeTable: number): Promise<boolean> {
+    const result = await this.run('ip', ['rule', 'show']);
+    return result.stdout
+      .split('\n')
+      .some((line) => line.includes(`from ${this.getSubnetCidr()}`) && line.includes(`lookup ${routeTable}`));
+  }
+
+  private async ensureWireGuardInterface(): Promise<string> {
+    if (!this.wireguard) {
+      throw new Error('WireGuard is not configured');
+    }
+
+    if ('existingInterface' in this.wireguard) {
+      await this.runChecked('ip', ['link', 'show', this.wireguard.existingInterface]);
+      this.wireGuardManaged = false;
+      return this.wireguard.existingInterface;
+    }
+
+    const iface = this.wireguard.interfaceName || 'svwg0';
+    const existingInterface = await this.run('ip', ['link', 'show', iface]);
+    if (existingInterface.exitCode === 0) {
+      throw new SmartVMError(
+        `Managed WireGuard interface '${iface}' already exists; use existingInterface to route through it`,
+        'WIREGUARD_SETUP_FAILED',
+      );
+    }
+
+    const parsedConfig = this.parseWireGuardConfig(this.wireguard.config);
+    await this.runChecked('ip', ['link', 'add', 'dev', iface, 'type', 'wireguard']);
+    this.wireGuardManaged = true;
+    this.wireGuardInterface = iface;
+
+    const tempDir = await plugins.fs.promises.mkdtemp(
+      plugins.path.join(this.getSharedMemoryTempDir(), `smartvm-wg-${iface}-`),
+    );
+    const tempConfigPath = plugins.path.join(tempDir, 'wg.conf');
+    try {
+      await plugins.fs.promises.writeFile(tempConfigPath, parsedConfig.setConfig, { mode: 0o600 });
+      await this.runChecked('wg', ['setconf', iface, tempConfigPath]);
+    } finally {
+      await plugins.fs.promises.rm(tempDir, { recursive: true, force: true });
+    }
+
+    for (const address of parsedConfig.addresses) {
+      await this.runChecked('ip', ['addr', 'add', address, 'dev', iface]);
+    }
+    if (parsedConfig.mtu !== undefined) {
+      await this.runChecked('ip', ['link', 'set', 'mtu', String(parsedConfig.mtu), 'dev', iface]);
+    }
+    await this.runChecked('ip', ['link', 'set', iface, 'up']);
+    return iface;
+  }
+
+  private shouldApplyFailClosed(): boolean {
+    return Boolean(
+      this.wireguard &&
+      this.wireguard.routeAllVmTraffic !== false &&
+      this.wireguard.failClosed !== false &&
+      this.wireGuardInterface,
+    );
+  }
+
+  private async setupNat(egressInterface: string): Promise<void> {
+    this.natRuleAdded = false;
+    const ruleArgs = [
+      '-s',
+      this.getSubnetCidr(),
+      '-o',
+      egressInterface,
+      '-j',
+      'MASQUERADE',
+    ];
+    const checkResult = await this.run('iptables', ['-t', 'nat', '-C', 'POSTROUTING', ...ruleArgs]);
+    if (checkResult.exitCode !== 0) {
+      await this.runChecked('iptables', ['-t', 'nat', '-A', 'POSTROUTING', ...ruleArgs]);
+      this.natRuleAdded = true;
+    }
+    this.natInterface = egressInterface;
+    this.natConfigured = true;
+  }
+
+  private async setupEgressFirewall(egressInterface: string): Promise<void> {
+    const egress = this.firewall?.egress;
+    const shouldSetupFirewall = Boolean(egress || this.shouldApplyFailClosed());
+    if (!shouldSetupFirewall) {
+      return;
+    }
+
+    await this.ensureIptablesChain('filter', this.firewallChainName);
+    this.firewallConfigured = true;
+    await this.runChecked('iptables', ['-t', 'filter', '-F', this.firewallChainName]);
+    await this.ensureIptablesRule('filter', 'FORWARD', ['-s', this.getSubnetCidr(), '-j', this.firewallChainName]);
+    await this.runChecked('iptables', [
+      '-t',
+      'filter',
+      '-A',
+      this.firewallChainName,
+      '-m',
+      'conntrack',
+      '--ctstate',
+      'ESTABLISHED,RELATED',
+      '-j',
+      'ACCEPT',
+    ]);
+
+    if (this.shouldApplyFailClosed()) {
+      await this.runChecked('iptables', [
+        '-t',
+        'filter',
+        '-A',
+        this.firewallChainName,
+        '!',
+        '-o',
+        egressInterface,
+        '-j',
+        'DROP',
+      ]);
+    }
+
+    for (const rule of egress?.rules || []) {
+      for (const ruleArgs of this.buildFirewallRuleArgs(rule)) {
+        await this.runChecked('iptables', ['-t', 'filter', '-A', this.firewallChainName, ...ruleArgs]);
+      }
+    }
+
+    const defaultAction = egress?.defaultAction || 'allow';
+    await this.runChecked('iptables', [
+      '-t',
+      'filter',
+      '-A',
+      this.firewallChainName,
+      '-j',
+      FIREWALL_ACTION_TO_IPTABLES_TARGET[defaultAction],
+    ]);
+  }
+
+  private buildFirewallRuleArgs(rule: IFirewallRule): string[][] {
+    const baseArgs: string[] = [];
+    const protocol = rule.protocol || 'all';
+    if (rule.to !== undefined) {
+      baseArgs.push('-d', this.normalizeCidr(rule.to));
+    }
+    if (protocol !== 'all') {
+      baseArgs.push('-p', protocol);
+    }
+    if (rule.comment) {
+      baseArgs.push('-m', 'comment', '--comment', rule.comment.slice(0, 240));
+    }
+
+    const target = FIREWALL_ACTION_TO_IPTABLES_TARGET[rule.action];
+    const ports = this.normalizePorts(rule.ports);
+    if (ports.length === 0) {
+      return [[...baseArgs, '-j', target]];
+    }
+    return ports.map((port) => [...baseArgs, '--dport', String(port), '-j', target]);
+  }
+
+  private async ensureIptablesChain(table: string, chain: string): Promise<void> {
+    const checkResult = await this.run('iptables', ['-t', table, '-S', chain]);
+    if (checkResult.exitCode !== 0) {
+      await this.runChecked('iptables', ['-t', table, '-N', chain]);
+    }
+  }
+
+  private async ensureIptablesRule(table: string, chain: string, ruleArgs: string[]): Promise<void> {
+    const checkResult = await this.run('iptables', ['-t', table, '-C', chain, ...ruleArgs]);
+    if (checkResult.exitCode !== 0) {
+      await this.runChecked('iptables', ['-t', table, '-A', chain, ...ruleArgs]);
+    }
+  }
+
+  private async deleteIptablesRule(table: string, chain: string, ruleArgs: string[]): Promise<void> {
+    await this.run('iptables', ['-t', table, '-D', chain, ...ruleArgs]);
+  }
+
   /**
    * Ensure the Linux bridge is created and configured.
    */
   public async ensureBridge(): Promise<void> {
     if (this.bridgeCreated) return;
 
+    let createdBridge = false;
     try {
       // Check if bridge already exists
-      const result = await this.shell.exec(`ip link show ${this.bridgeName} 2>/dev/null`);
+      const result = await this.run('ip', ['link', 'show', this.bridgeName]);
       if (result.exitCode !== 0) {
         // Create bridge
-        await this.shell.exec(`ip link add ${this.bridgeName} type bridge`);
-        await this.shell.exec(`ip addr add ${this.gatewayIp}/${this.subnetCidr} dev ${this.bridgeName}`);
-        await this.shell.exec(`ip link set ${this.bridgeName} up`);
+        await this.runChecked('ip', ['link', 'add', this.bridgeName, 'type', 'bridge']);
+        createdBridge = true;
+        await this.runChecked('ip', ['addr', 'add', `${this.gatewayIp}/${this.subnetCidr}`, 'dev', this.bridgeName]);
+        await this.runChecked('ip', ['link', 'set', this.bridgeName, 'up']);
       }
 
       // Enable IP forwarding
-      await this.shell.exec('sysctl -w net.ipv4.ip_forward=1');
+      await this.runChecked('sysctl', ['-w', 'net.ipv4.ip_forward=1']);
 
-      // Set up NAT masquerade (idempotent with -C check)
-      const checkResult = await this.shell.exec(
-        `iptables -t nat -C POSTROUTING -s ${this.subnetBase}/${this.subnetCidr} -o $(ip route | grep default | awk '{print $5}' | head -1) -j MASQUERADE 2>/dev/null`,
-      );
-      if (checkResult.exitCode !== 0) {
-        await this.shell.exec(
-          `iptables -t nat -A POSTROUTING -s ${this.subnetBase}/${this.subnetCidr} -o $(ip route | grep default | awk '{print $5}' | head -1) -j MASQUERADE`,
-        );
-      }
+      const egressInterface = await this.configureWireGuardEgress();
+      await this.setupEgressFirewall(egressInterface);
+      await this.setupNat(egressInterface);
 
       this.bridgeCreated = true;
     } catch (err) {
+      try {
+        await this.cleanupEgressFirewall();
+        await this.cleanupNat();
+        await this.cleanupWireGuardEgress();
+        if (createdBridge) {
+          await this.run('ip', ['link', 'set', this.bridgeName, 'down']);
+          await this.run('ip', ['link', 'del', this.bridgeName]);
+        }
+      } catch {
+        // Preserve the original setup error.
+      }
+      if (err instanceof SmartVMError) {
+        throw err;
+      }
       const message = err instanceof Error ? err.message : String(err);
       throw new SmartVMError(
         `Failed to set up network bridge: ${message}`,
@@ -148,16 +836,19 @@ export class NetworkManager {
     await this.ensureBridge();
 
     const tapName = this.generateTapName(vmId, ifaceId);
+    this.validateInterfaceName(tapName, 'tapName');
     const guestIp = this.allocateIp();
     const mac = this.generateMac(vmId, ifaceId);
+    let tapCreated = false;
 
     try {
       // Create TAP device
-      await this.shell.exec(`ip tuntap add dev ${tapName} mode tap`);
+      await this.runChecked('ip', ['tuntap', 'add', 'dev', tapName, 'mode', 'tap']);
+      tapCreated = true;
       // Attach to bridge
-      await this.shell.exec(`ip link set ${tapName} master ${this.bridgeName}`);
+      await this.runChecked('ip', ['link', 'set', tapName, 'master', this.bridgeName]);
       // Bring TAP device up
-      await this.shell.exec(`ip link set ${tapName} up`);
+      await this.runChecked('ip', ['link', 'set', tapName, 'up']);
 
       const tap: ITapDevice = {
         tapName,
@@ -170,6 +861,9 @@ export class NetworkManager {
       this.activeTaps.set(tapName, tap);
       return tap;
     } catch (err) {
+      if (tapCreated) {
+        await this.removeTapDevice(tapName);
+      }
       const message = err instanceof Error ? err.message : String(err);
       throw new SmartVMError(
         `Failed to create TAP device ${tapName}: ${message}`,
@@ -182,8 +876,9 @@ export class NetworkManager {
    * Remove a TAP device and free its resources.
    */
   public async removeTapDevice(tapName: string): Promise<void> {
+    this.validateInterfaceName(tapName, 'tapName');
     try {
-      await this.shell.exec(`ip link del ${tapName} 2>/dev/null`);
+      await this.run('ip', ['link', 'del', tapName]);
       this.activeTaps.delete(tapName);
     } catch {
       // Device may already be gone
@@ -211,29 +906,95 @@ export class NetworkManager {
    */
   public async cleanup(): Promise<void> {
     // Remove all TAP devices
-    for (const tapName of this.activeTaps.keys()) {
+    for (const tapName of Array.from(this.activeTaps.keys())) {
       await this.removeTapDevice(tapName);
     }
 
+    await this.cleanupEgressFirewall();
+    await this.cleanupNat();
+    await this.cleanupWireGuardEgress();
+
     // Remove bridge if we created it
     if (this.bridgeCreated) {
       try {
-        await this.shell.exec(`ip link set ${this.bridgeName} down 2>/dev/null`);
-        await this.shell.exec(`ip link del ${this.bridgeName} 2>/dev/null`);
+        await this.run('ip', ['link', 'set', this.bridgeName, 'down']);
+        await this.run('ip', ['link', 'del', this.bridgeName]);
       } catch {
         // Bridge may already be gone
       }
 
-      // Remove NAT rule
-      try {
-        await this.shell.exec(
-          `iptables -t nat -D POSTROUTING -s ${this.subnetBase}/${this.subnetCidr} -o $(ip route | grep default | awk '{print $5}' | head -1) -j MASQUERADE 2>/dev/null`,
-        );
-      } catch {
-        // Rule may not exist
-      }
-
       this.bridgeCreated = false;
     }
   }
+
+  private async cleanupEgressFirewall(): Promise<void> {
+    if (!this.firewallConfigured) {
+      return;
+    }
+    await this.deleteIptablesRule('filter', 'FORWARD', [
+      '-s',
+      this.getSubnetCidr(),
+      '-j',
+      this.firewallChainName,
+    ]);
+    await this.run('iptables', ['-t', 'filter', '-F', this.firewallChainName]);
+    await this.run('iptables', ['-t', 'filter', '-X', this.firewallChainName]);
+    this.firewallConfigured = false;
+  }
+
+  private async cleanupNat(): Promise<void> {
+    if (!this.natConfigured || !this.natInterface) {
+      return;
+    }
+    if (this.natRuleAdded) {
+      await this.deleteIptablesRule('nat', 'POSTROUTING', [
+        '-s',
+        this.getSubnetCidr(),
+        '-o',
+        this.natInterface,
+        '-j',
+        'MASQUERADE',
+      ]);
+    }
+    this.natInterface = null;
+    this.natConfigured = false;
+    this.natRuleAdded = false;
+  }
+
+  private async cleanupWireGuardEgress(): Promise<void> {
+    if (this.wireGuardRouteConfigured && this.wireGuardRouteTable !== null) {
+      if (this.wireGuardIpRuleAdded) {
+        await this.run('ip', [
+          'rule',
+          'del',
+          'from',
+          this.getSubnetCidr(),
+          'table',
+          String(this.wireGuardRouteTable),
+        ]);
+      }
+      if (this.wireGuardRouteAdded && this.wireGuardInterface) {
+        await this.run('ip', [
+          'route',
+          'del',
+          'default',
+          'dev',
+          this.wireGuardInterface,
+          'table',
+          String(this.wireGuardRouteTable),
+        ]);
+      }
+    }
+
+    if (this.wireGuardManaged && this.wireGuardInterface) {
+      await this.run('ip', ['link', 'del', this.wireGuardInterface]);
+    }
+
+    this.wireGuardRouteConfigured = false;
+    this.wireGuardRouteAdded = false;
+    this.wireGuardIpRuleAdded = false;
+    this.wireGuardRouteTable = null;
+    this.wireGuardManaged = false;
+    this.wireGuardInterface = null;
+  }
 }

ts/classes.smartvm.ts

@@ -1,16 +1,22 @@
 import * as plugins from './plugins.js';
-import type { ISmartVMOptions, IMicroVMConfig } from './interfaces/index.js';
+import type { IBaseImageBundle, IEnsureBaseImageOptions, ISmartVMOptions, IMicroVMConfig } from './interfaces/index.js';
 import { SmartVMError } from './interfaces/index.js';
 import { ImageManager } from './classes.imagemanager.js';
+import { BaseImageManager } from './classes.baseimagemanager.js';
 import { NetworkManager } from './classes.networkmanager.js';
 import { MicroVM } from './classes.microvm.js';
 
+function getErrorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
 /**
  * Top-level orchestrator for creating and managing Firecracker MicroVMs.
  */
 export class SmartVM {
   private options: ISmartVMOptions;
   public imageManager: ImageManager;
+  public baseImageManager: BaseImageManager;
   public networkManager: NetworkManager;
   private activeVMs: Map<string, MicroVM> = new Map();
   private smartExitInstance: InstanceType<typeof plugins.smartexit.SmartExit>;
@@ -20,6 +26,8 @@ export class SmartVM {
   constructor(options: ISmartVMOptions = {}) {
     this.options = {
       dataDir: options.dataDir || '/tmp/.smartvm',
+      runtimeDir: options.runtimeDir || this.getDefaultRuntimeDir(),
+      ephemeralWritableDrives: options.ephemeralWritableDrives ?? true,
       arch: options.arch || 'x86_64',
       bridgeName: options.bridgeName || 'svbr0',
       subnet: options.subnet || '172.30.0.0/24',
@@ -27,9 +35,18 @@ export class SmartVM {
     };
 
     this.imageManager = new ImageManager(this.options.dataDir!, this.options.arch);
+    this.baseImageManager = new BaseImageManager({
+      arch: this.options.arch,
+      cacheDir: this.options.baseImageCacheDir,
+      maxStoredBaseImages: this.options.maxStoredBaseImages,
+      hostedManifestUrl: this.options.baseImageManifestUrl,
+      hostedManifestPath: this.options.baseImageManifestPath,
+    });
     this.networkManager = new NetworkManager({
       bridgeName: this.options.bridgeName,
       subnet: this.options.subnet,
+      firewall: this.options.firewall,
+      wireguard: this.options.wireguard,
     });
 
     // If a custom binary path is provided, use it directly
@@ -44,6 +61,30 @@ export class SmartVM {
     });
   }
 
+  private getDefaultRuntimeDir(): string {
+    const tmpfsDir = '/dev/shm';
+    try {
+      if (plugins.fs.existsSync(tmpfsDir) && plugins.fs.statSync(tmpfsDir).isDirectory()) {
+        return plugins.path.join(tmpfsDir, '.smartvm', 'runtime');
+      }
+    } catch {
+      // Fall back to os.tmpdir() below.
+    }
+    return plugins.path.join(plugins.os.tmpdir(), '.smartvm', 'runtime');
+  }
+
+  public getRuntimeDir(): string {
+    return this.options.runtimeDir!;
+  }
+
+  private sanitizePathPart(value: string): string {
+    const sanitized = value.replace(/[^a-zA-Z0-9._-]/g, '_');
+    if (!sanitized || sanitized === '.' || sanitized === '..') {
+      return 'item';
+    }
+    return sanitized;
+  }
+
   /**
    * Ensure the Firecracker binary is available.
    * Downloads it if not present.
@@ -97,8 +138,9 @@ export class SmartVM {
     // Generate VM ID if not provided
     const vmId = config.id || plugins.smartunique.uuid4();
 
-    // Generate socket path
-    const socketPath = this.imageManager.getSocketPath(vmId);
+    // Keep per-VM runtime artifacts in tmpfs by default.
+    const vmRuntimeDir = plugins.path.join(this.options.runtimeDir!, this.sanitizePathPart(vmId));
+    const socketPath = plugins.path.join(vmRuntimeDir, 'firecracker.sock');
 
     // Create MicroVM instance
     const vm = new MicroVM(
@@ -107,6 +149,10 @@ export class SmartVM {
       this.firecrackerBinaryPath!,
       socketPath,
       this.networkManager,
+      {
+        runtimeDir: this.options.runtimeDir,
+        ephemeralWritableDrives: this.options.ephemeralWritableDrives,
+      },
     );
 
     // Register in active VMs
@@ -115,6 +161,13 @@ export class SmartVM {
     return vm;
   }
 
+  /**
+   * Ensure a Firecracker CI base image bundle is available locally.
+   */
+  public async ensureBaseImage(options: IEnsureBaseImageOptions = {}): Promise<IBaseImageBundle> {
+    return this.baseImageManager.ensureBaseImage(options);
+  }
+
   /**
    * Get an active VM by ID.
    */
@@ -145,7 +198,7 @@ export class SmartVM {
       if (vm.state === 'running' || vm.state === 'paused') {
         stopPromises.push(
           vm.stop().catch((err) => {
-            console.error(`Failed to stop VM ${vm.id}: ${err.message}`);
+            console.error(`Failed to stop VM ${vm.id}: ${getErrorMessage(err)}`);
           }),
         );
       }
@@ -162,7 +215,7 @@ export class SmartVM {
     for (const vm of this.activeVMs.values()) {
       cleanupPromises.push(
         vm.cleanup().catch((err) => {
-          console.error(`Failed to clean up VM ${vm.id}: ${err.message}`);
+          console.error(`Failed to clean up VM ${vm.id}: ${getErrorMessage(err)}`);
         }),
       );
     }

ts/classes.socketclient.ts

@@ -2,6 +2,10 @@ import * as plugins from './plugins.js';
 import type { ISocketClientOptions, IApiResponse } from './interfaces/index.js';
 import { SmartVMError } from './interfaces/index.js';
 
+function getErrorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
 /**
  * HTTP client that communicates with Firecracker over a Unix domain socket.
  * Uses @push.rocks/smartrequest with the `http://unix:<socket>:<path>` URL format.
@@ -20,6 +24,22 @@ export class SocketClient {
     return `http://unix:${this.socketPath}:${apiPath}`;
   }
 
+  private async parseResponseBody<T>(response: any): Promise<T> {
+    try {
+      const text = await response.text();
+      if (!text) {
+        return undefined as T;
+      }
+      try {
+        return JSON.parse(text) as T;
+      } catch {
+        return text as T;
+      }
+    } catch {
+      return undefined as T;
+    }
+  }
+
   /**
    * Perform a GET request.
    */
@@ -31,12 +51,7 @@ export class SocketClient {
         .get();
 
       const statusCode = response.status;
-      let body: T;
-      try {
-        body = await response.json() as T;
-      } catch {
-        body = undefined as any;
-      }
+      const body = await this.parseResponseBody<T>(response);
       return {
         statusCode,
         body,
@@ -44,7 +59,7 @@ export class SocketClient {
       };
     } catch (err) {
       throw new SmartVMError(
-        `GET ${apiPath} failed: ${(err as Error).message}`,
+        `GET ${apiPath} failed: ${getErrorMessage(err)}`,
         'SOCKET_REQUEST_FAILED',
       );
     }
@@ -54,21 +69,19 @@ export class SocketClient {
    * Perform a PUT request with a JSON body.
    */
   public async put<T = any>(apiPath: string, body?: Record<string, any>): Promise<IApiResponse<T>> {
-    const url = this.buildUrl(apiPath);
-    try {
-      let request = plugins.SmartRequest.create().url(url);
-      if (body !== undefined) {
-        request = request.json(body);
-      }
+      const url = this.buildUrl(apiPath);
+      try {
+        let request = plugins.SmartRequest.create().url(url);
+        if (body !== undefined) {
+        const bodyBuffer = Buffer.from(JSON.stringify(body));
+        request = request
+          .buffer(bodyBuffer, 'application/json')
+          .header('Content-Length', String(bodyBuffer.length));
+        }
       const response = await request.put();
 
       const statusCode = response.status;
-      let responseBody: T;
-      try {
-        responseBody = await response.json() as T;
-      } catch {
-        responseBody = undefined as any;
-      }
+      const responseBody = await this.parseResponseBody<T>(response);
       return {
         statusCode,
         body: responseBody,
@@ -76,7 +89,7 @@ export class SocketClient {
       };
     } catch (err) {
       throw new SmartVMError(
-        `PUT ${apiPath} failed: ${(err as Error).message}`,
+        `PUT ${apiPath} failed: ${getErrorMessage(err)}`,
         'SOCKET_REQUEST_FAILED',
       );
     }
@@ -86,21 +99,19 @@ export class SocketClient {
    * Perform a PATCH request with a JSON body.
    */
   public async patch<T = any>(apiPath: string, body?: Record<string, any>): Promise<IApiResponse<T>> {
-    const url = this.buildUrl(apiPath);
-    try {
-      let request = plugins.SmartRequest.create().url(url);
-      if (body !== undefined) {
-        request = request.json(body);
-      }
+      const url = this.buildUrl(apiPath);
+      try {
+        let request = plugins.SmartRequest.create().url(url);
+        if (body !== undefined) {
+        const bodyBuffer = Buffer.from(JSON.stringify(body));
+        request = request
+          .buffer(bodyBuffer, 'application/json')
+          .header('Content-Length', String(bodyBuffer.length));
+        }
       const response = await request.patch();
 
       const statusCode = response.status;
-      let responseBody: T;
-      try {
-        responseBody = await response.json() as T;
-      } catch {
-        responseBody = undefined as any;
-      }
+      const responseBody = await this.parseResponseBody<T>(response);
       return {
         statusCode,
         body: responseBody,
@@ -108,21 +119,21 @@ export class SocketClient {
       };
     } catch (err) {
       throw new SmartVMError(
-        `PATCH ${apiPath} failed: ${(err as Error).message}`,
+        `PATCH ${apiPath} failed: ${getErrorMessage(err)}`,
         'SOCKET_REQUEST_FAILED',
       );
     }
   }
 
   /**
-   * Check if the Firecracker API socket is ready by polling GET /.
+   * Check if the Firecracker API socket is ready by polling GET /version.
    */
   public async isReady(timeoutMs: number = 5000): Promise<boolean> {
     const start = Date.now();
     while (Date.now() - start < timeoutMs) {
       try {
-        const response = await this.get('/');
-        if (response.ok || response.statusCode === 200 || response.statusCode === 400) {
+        const response = await this.get('/version');
+        if (response.ok) {
           return true;
         }
       } catch {

ts/classes.vmconfig.ts

@@ -12,7 +12,45 @@ export class VMConfig {
   public config: IMicroVMConfig;
 
   constructor(config: IMicroVMConfig) {
-    this.config = config;
+    this.config = this.cloneConfig(config);
+  }
+
+  /**
+   * Keep internal normalization from mutating the caller's config object.
+   */
+  private cloneConfig(config: IMicroVMConfig): IMicroVMConfig {
+    return {
+      ...config,
+      bootSource: config.bootSource ? { ...config.bootSource } : config.bootSource,
+      machineConfig: config.machineConfig ? { ...config.machineConfig } : config.machineConfig,
+      drives: config.drives?.map((drive) => ({
+        ...drive,
+        rateLimiter: drive.rateLimiter ? this.cloneRateLimiter(drive.rateLimiter) : undefined,
+        ephemeral: drive.ephemeral,
+      })),
+      networkInterfaces: config.networkInterfaces?.map((iface) => ({
+        ...iface,
+        rxRateLimiter: iface.rxRateLimiter ? this.cloneRateLimiter(iface.rxRateLimiter) : undefined,
+        txRateLimiter: iface.txRateLimiter ? this.cloneRateLimiter(iface.txRateLimiter) : undefined,
+      })),
+      vsock: config.vsock ? { ...config.vsock } : undefined,
+      balloon: config.balloon ? { ...config.balloon } : undefined,
+      mmds: config.mmds ? {
+        ...config.mmds,
+        networkInterfaces: config.mmds.networkInterfaces
+          ? [...config.mmds.networkInterfaces]
+          : config.mmds.networkInterfaces,
+      } : undefined,
+      logger: config.logger ? { ...config.logger } : undefined,
+      metrics: config.metrics ? { ...config.metrics } : undefined,
+    };
+  }
+
+  private cloneRateLimiter(rateLimiter: IRateLimiter): IRateLimiter {
+    return {
+      bandwidth: rateLimiter.bandwidth ? { ...rateLimiter.bandwidth } : undefined,
+      ops: rateLimiter.ops ? { ...rateLimiter.ops } : undefined,
+    };
   }
 
   /**

ts/index.ts

@@ -2,6 +2,7 @@ export * from './interfaces/index.js';
 export { VMConfig } from './classes.vmconfig.js';
 export { SocketClient } from './classes.socketclient.js';
 export { ImageManager } from './classes.imagemanager.js';
+export { BaseImageManager } from './classes.baseimagemanager.js';
 export { FirecrackerProcess } from './classes.firecrackerprocess.js';
 export { NetworkManager } from './classes.networkmanager.js';
 export { MicroVM } from './classes.microvm.js';

ts/interfaces/config.ts

@@ -6,6 +6,10 @@ import type { TFirecrackerArch, TCacheType, TSnapshotType, TLogLevel } from './c
 export interface ISmartVMOptions {
   /** Directory for storing binaries, kernels, rootfs images, and sockets. Defaults to /tmp/.smartvm */
   dataDir?: string;
+  /** Directory for VM sockets and ephemeral per-VM files. Defaults to /dev/shm/.smartvm/runtime on Linux when available. */
+  runtimeDir?: string;
+  /** Copy writable drives into the VM runtime directory before boot and delete them on cleanup. Defaults to true. */
+  ephemeralWritableDrives?: boolean;
   /** Firecracker version to use. Defaults to latest. */
   firecrackerVersion?: string;
   /** Target architecture. Defaults to x86_64. */
@@ -16,8 +20,204 @@ export interface ISmartVMOptions {
   bridgeName?: string;
   /** Network subnet in CIDR notation. Defaults to '172.30.0.0/24'. */
   subnet?: string;
+  /** VM egress firewall configuration. */
+  firewall?: IFirewallConfig;
+  /** Host-side WireGuard egress routing configuration for VM traffic. */
+  wireguard?: TWireGuardConfig;
+  /** Directory for cached base images. Defaults to /tmp/.smartvm/base-images. */
+  baseImageCacheDir?: string;
+  /** Maximum number of cached base image bundles. Defaults to 2. */
+  maxStoredBaseImages?: number;
+  /** Hosted/project-owned base image manifest URL. */
+  baseImageManifestUrl?: string;
+  /** Local hosted/project-owned base image manifest path for development and tests. */
+  baseImageManifestPath?: string;
 }
 
+/**
+ * Predefined base image sources for integration testing and quick starts.
+ */
+export type TBaseImagePreset = 'latest' | 'lts' | 'hosted';
+
+/**
+ * Root filesystem image type used by a base image bundle.
+ */
+export type TBaseImageRootfsType = 'ext4' | 'squashfs';
+
+/**
+ * Options for the BaseImageManager.
+ */
+export interface IBaseImageManagerOptions {
+  /** Architecture to resolve. Defaults to x86_64. */
+  arch?: TFirecrackerArch;
+  /** Directory for cached base image bundles. Defaults to /tmp/.smartvm/base-images. */
+  cacheDir?: string;
+  /** Maximum number of cached base image bundles. Defaults to 2. */
+  maxStoredBaseImages?: number;
+  /** Hosted base image manifest URL for project-owned bundles. */
+  hostedManifestUrl?: string;
+  /** Local hosted base image manifest path for development and tests. */
+  hostedManifestPath?: string;
+}
+
+/**
+ * Options when resolving or downloading a base image bundle.
+ */
+export interface IEnsureBaseImageOptions {
+  /** Preset to use. Defaults to latest. */
+  preset?: TBaseImagePreset;
+  /** Architecture to resolve. Defaults to manager architecture. */
+  arch?: TFirecrackerArch;
+  /** Redownload even if the bundle already exists locally. */
+  forceDownload?: boolean;
+  /** Hosted base image manifest URL. Overrides preset resolution. */
+  manifestUrl?: string;
+  /** Local hosted base image manifest path. Overrides preset resolution. */
+  manifestPath?: string;
+}
+
+/**
+ * Single hosted base image artifact in a manifest.
+ */
+export interface IBaseImageArtifactManifest {
+  /** Public URL for hosted artifacts. */
+  url?: string;
+  /** Local path for development/tests. */
+  path?: string;
+  /** Optional plain output filename. Defaults to basename of url/path. */
+  fileName?: string;
+  /** Expected SHA256 for verification. Required when url is used. */
+  sha256?: string;
+  /** Expected file size in bytes. */
+  sizeBytes?: number;
+}
+
+/**
+ * Hosted/project-owned base image manifest format.
+ */
+export interface IBaseImageHostedManifest {
+  schemaVersion: 1;
+  bundleId: string;
+  name?: string;
+  arch: TFirecrackerArch;
+  firecrackerVersion: string;
+  rootfsType: TBaseImageRootfsType;
+  rootfsIsReadOnly?: boolean;
+  bootArgs?: string;
+  kernel: IBaseImageArtifactManifest;
+  rootfs: IBaseImageArtifactManifest;
+}
+
+/**
+ * Cached base image bundle metadata.
+ */
+export interface IBaseImageBundle {
+  preset: TBaseImagePreset;
+  arch: TFirecrackerArch;
+  ciVersion: string;
+  firecrackerVersion: string;
+  bundleId: string;
+  bundleDir: string;
+  kernelImagePath: string;
+  rootfsPath: string;
+  rootfsType: TBaseImageRootfsType;
+  rootfsIsReadOnly: boolean;
+  bootArgs: string;
+  source: {
+    type?: 'firecracker-ci' | 'hosted-manifest';
+    bucketUrl?: string;
+    kernelKey?: string;
+    rootfsKey?: string;
+    manifestUrl?: string;
+    manifestPath?: string;
+    kernelUrl?: string;
+    rootfsUrl?: string;
+    kernelSourcePath?: string;
+    rootfsSourcePath?: string;
+  };
+  checksums?: {
+    kernelSha256?: string;
+    rootfsSha256?: string;
+  };
+  sizes?: {
+    kernelBytes?: number;
+    rootfsBytes?: number;
+  };
+  createdAt: string;
+  lastAccessedAt: string;
+}
+
+/**
+ * Runtime behavior for a MicroVM instance.
+ */
+export interface IMicroVMRuntimeOptions {
+  /** Directory for VM sockets and ephemeral per-VM files. */
+  runtimeDir?: string;
+  /** Copy writable drives into runtimeDir before boot and delete them on cleanup. Defaults to true. */
+  ephemeralWritableDrives?: boolean;
+}
+
+/** Firewall action for VM egress traffic. */
+export type TFirewallAction = 'allow' | 'deny';
+
+/** Firewall protocol selector for VM egress traffic. */
+export type TFirewallProtocol = 'all' | 'tcp' | 'udp' | 'icmp';
+
+/** One ordered VM egress firewall rule. */
+export interface IFirewallRule {
+  /** Rule action. */
+  action: TFirewallAction;
+  /** Destination IPv4 address or CIDR. Omit to match all destinations. */
+  to?: string;
+  /** Protocol to match. Defaults to all. */
+  protocol?: TFirewallProtocol;
+  /** Destination port or ports for tcp/udp rules. */
+  ports?: number | number[];
+  /** Optional human-readable rule label. */
+  comment?: string;
+}
+
+/** VM egress firewall policy. */
+export interface IFirewallEgressConfig {
+  /** Final action when no rule matches. Defaults to allow. */
+  defaultAction?: TFirewallAction;
+  /** Ordered rules; first match wins. */
+  rules?: IFirewallRule[];
+}
+
+/** Firewall configuration. */
+export interface IFirewallConfig {
+  /** Egress firewall for traffic leaving the VM subnet. */
+  egress?: IFirewallEgressConfig;
+}
+
+/** Common WireGuard routing options. */
+export interface IWireGuardBaseConfig {
+  /** Route all VM subnet traffic through this WireGuard interface. Defaults to true. */
+  routeAllVmTraffic?: boolean;
+  /** Drop VM traffic that would leave through a non-WireGuard interface. Defaults to true. */
+  failClosed?: boolean;
+  /** Linux routing table number for VM WireGuard egress. Defaults to 51820. */
+  routeTable?: number;
+}
+
+/** Managed WireGuard interface created and removed by smartvm. */
+export interface IWireGuardManagedConfig extends IWireGuardBaseConfig {
+  /** wg-quick-style WireGuard config text. Hook fields are rejected. */
+  config: string;
+  /** Interface name to create. Defaults to svwg0. */
+  interfaceName?: string;
+}
+
+/** Existing WireGuard interface owned outside smartvm. */
+export interface IWireGuardExistingInterfaceConfig extends IWireGuardBaseConfig {
+  /** Existing WireGuard interface to route VM traffic through. */
+  existingInterface: string;
+}
+
+/** WireGuard egress configuration. */
+export type TWireGuardConfig = IWireGuardManagedConfig | IWireGuardExistingInterfaceConfig;
+
 /**
  * Firecracker boot source configuration.
  */
@@ -84,6 +284,8 @@ export interface IDriveConfig {
   rateLimiter?: IRateLimiter;
   /** Path to a file that backs the device for I/O. */
   ioEngine?: string;
+  /** Whether this drive should be staged into per-VM ephemeral storage. Defaults to true for writable drives. */
+  ephemeral?: boolean;
 }
 
 /**
@@ -142,9 +344,9 @@ export interface ILoggerConfig {
   logPath: string;
   /** Log level. */
   level?: TLogLevel;
-  /** Whether to show log origin (file, line). */
-  showLevel?: boolean;
   /** Whether to show log level. */
+  showLevel?: boolean;
+  /** Whether to show log origin (file, line). */
   showLogOrigin?: boolean;
 }
 
@@ -216,6 +418,10 @@ export interface INetworkManagerOptions {
   bridgeName?: string;
   /** Subnet in CIDR notation. Defaults to '172.30.0.0/24'. */
   subnet?: string;
+  /** VM egress firewall configuration. */
+  firewall?: IFirewallConfig;
+  /** Host-side WireGuard egress routing configuration for VM traffic. */
+  wireguard?: TWireGuardConfig;
 }
 
 /**

ts/plugins.ts

@@ -2,8 +2,9 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
+import * as crypto from 'crypto';
 
-export { fs, path, os };
+export { fs, path, os, crypto };
 
 // @push.rocks scope
 import * as smartdelay from '@push.rocks/smartdelay';