varc
Rootless Single-File Container Runtime & Declarative Orchestrator

varc — Rootless Single-File Container Runtime & Declarative Orchestrator

varc Brand Logo

varc (V Application Runtime & Containers) is a self-contained, zero-daemon, rootless container runtime, single-file image packager, zero-root virtual network overlay, Copy-on-Write (CoW) volume engine, and declarative multi-service orchestrator. It packages OS containers, OCI directory layouts, and WebAssembly 3.0 sandboxes into cryptographically signed .varc single-file bundles that verify and launch in milliseconds without requiring root privileges, background daemons, or external container tooling.

varc Developer Portal — Registered Single-File Container Bundles


Core Capabilities

Capability Operational Benefit
Single-File .varc Bundles Package application binaries, assets, OCI layouts, or Wasm modules into one immutable, Ed25519-signed .varc artifact with 4 KB SHA-256 Merkle chunk deduplication.
Rootless Multi-Backend Runtime Launch workloads across native Linux unprivileged namespaces (CLONE_NEWUSER, CLONE_NEWNS, CLONE_NEWPID, CLONE_NEWNET), transparent Windows-to-WSL2 bridges, or vvm WebAssembly 3.0 sandboxes.
Seccomp-BPF Monitor-to-Enforce Profile real workload system calls in monitor learning mode while blocking 41 high-risk kernel calls, then lock deterministic enforce BPF filters with one command or UI click.
Zero-Root 127.64.x.y VNet Mesh Assign collision-free 127.64.x.y loopback Virtual IPs and .varc / .vgate service DNS records without CAP_NET_ADMIN, TUN devices, or privileged CNI plugins.
Packed CAS CoW Volumes Capture, stream, and restore power-of-2 chunked (4 KB to 1024 KB) persistent volumes backed by an indexed Content-Addressable Storage arena (chunks.pack + chunks.idx).
Declarative Stacks & 1-Second Rollback Reconcile multi-service varc.conf stacks, Cron/Batch jobs, and horizontal autoscaling policies with atomic container + volume snapshot rollback.
4-Workspace Web Studio & REST API Operate clusters through an embedded Light/Dark Web Control Plane (/ui/auth, /ui/portal, /ui/delegated, /ui/admin) and OpenAPI 3.1 HTTP/1.1 server.

60-Second Quickstart

1. Generate a Signing Keypair & Package an Application

POWERSHELL
# Generate and pin a local Ed25519 bundle signing keypair
varc keygen --signer prod-release-ca --data-dir ./varc-data

# Package an application directory into a signed single-file .varc bundle
varc pack `
  --name hello-service `
  --version 1.0.0 `
  --dir ./examples/hello-service `
  --signer prod-release-ca `
  --tier network-service `
  --vip 127.64.2.10 `
  --out ./hello-service.varc `
  --data-dir ./varc-data

# Verify CRC32 framing, 4 KB Merkle root, and Ed25519 signature offline
varc verify ./hello-service.varc

2. Launch a Rootless Container & Inspect State

POWERSHELL
# Seal an encrypted runtime secret with AES-256-GCM
varc secret set db_password --value "s3cr3t-prod-credential" --data-dir ./varc-data

# Verify, materialize into CAS, and start the rootless container
varc run ./hello-service.varc `
  --id ctr-hello-01 `
  --name hello-api `
  --stack edge-api `
  --secret db_password `
  --data-dir ./varc-data

# List running containers, seccomp modes, and 127.64.x.y loopback VIPs
varc ps --data-dir ./varc-data

3. Start the 4-Workspace Web Studio Control Plane

POWERSHELL
# Start the HTTP/1.1 Control Plane and Web Studio on 127.0.0.1:8460
$env:VARC_API_TOKEN = "replace-with-strong-64-hex-operator-token"
varc serve --listen 127.0.0.1:8460 --data-dir ./varc-data

Open http://127.0.0.1:8460/ui/auth in any modern browser to authenticate and manage bundles, containers, seccomp policies, stacks, virtual networks, volumes, and hash-chained audit logs.


End-User Documentation Suite

Guide Audience & Scope
How-To Guide Task-oriented recipes for building .varc bundles, importing OCI directories, running rootless containers, locking seccomp profiles, configuring VNet VIPs, and managing CoW volumes.
User Guide Comprehensive walkthrough of workload lifecycles, Wasm 3.0 sandboxes, resource quotas, declarative stacks, Cron/Batch jobs, and all four Web Studio workspaces.
Administrator Guide Cluster bootstrap, API token & OIDC authentication, signer trust policies, AES-256-GCM secret rotation, multi-node scheduling, WAL compaction, CAS garbage collection, and audit verification.
Operations & Use Cases Production deployment blueprints (HA PostgreSQL, air-gapped edge delivery, trustnode.sh appliance fleets) and Day-2 incident response runbooks.
Configuration & CLI Reference Complete reference for all varc CLI subcommands, flags, environment variables, varc.conf declarative directives, and HTTP REST API endpoints.
Performance & Sizing Empirical 9-workload benchmark metrics, CoW volume chunk-sizing guidance, and node capacity planning.

How-To Guide

This guide provides step-by-step operational recipes for the most common packaging, runtime, security policy, networking, storage, and Web Studio workflows in varc.


1. Sign and Package a Directory into a .varc Bundle

Use varc keygen and varc pack to turn any self-contained service directory into an immutable, Ed25519-signed .varc bundle.

POWERSHELL
# 1. Create or load a named Ed25519 signing identity
varc keygen --signer release-eng-2026 --data-dir ./varc-data

# 2. Pack the directory into a signed single-file bundle
varc pack `
  --name checkout-api `
  --version 2.4.0 `
  --dir ./examples/hello-service `
  --entrypoint ./bin/hello-service `
  --seccomp monitor `
  --tier network-service `
  --net vnet `
  --vip 127.64.3.10 `
  --cpu 2000 `
  --memory 1024 `
  --signer release-eng-2026 `
  --out ./dist-bundles/checkout-api-2.4.0.varc `
  --data-dir ./varc-data

# 3. Inspect manifest metadata and verify cryptographic integrity
varc inspect ./dist-bundles/checkout-api-2.4.0.varc
varc verify ./dist-bundles/checkout-api-2.4.0.varc

2. Import an OCI Image Layout into .varc

Convert an unpacked OCI image directory (containing config.json and rootfs/) into a verified single-file .varc bundle with automatic path-traversal and tarbomb bounds checking:

POWERSHELL
varc import `
  --oci ./examples/oci-webapp `
  --name webapp-oci `
  --version 1.2.0 `
  --out ./dist-bundles/webapp-oci-1.2.0.varc `
  --data-dir ./varc-data

varc inspect ./dist-bundles/webapp-oci-1.2.0.varc --json

During import, varc validates archive relative paths, strips unsafe setuid/setgid mode bits (04000 / 02000), enforces a 1 GiB cumulative extraction ceiling, computes 4 KB SHA-256 Merkle chunk hashes, and signs the output bundle.


3. Launch Rootless Isolated Containers with Encrypted Secrets

Seal sensitive credentials in the node AES-256-GCM vault and mount them into a container's ephemeral secret directory without exposing plaintext in environment variables or image manifests:

POWERSHELL
# Store encrypted secrets in the node vault
varc secret set pg_dsn --value "postgres://app:s3cr3t@127.64.4.10:5432/orders" --data-dir ./varc-data
varc secret set jwt_hmac_key --value "9f8e7d6c5b4a39281716151413121110" --data-dir ./varc-data

# Run the verified bundle with strict signer verification and injected secrets
varc run ./dist-bundles/checkout-api-2.4.0.varc `
  --id ctr-checkout-01 `
  --name checkout-api `
  --stack commerce `
  --trust strict `
  --secret pg_dsn,jwt_hmac_key `
  --env LOG_LEVEL=info,PORT=8080 `
  --data-dir ./varc-data

# Check container status, runtime backend, and loopback VIP
varc ps --data-dir ./varc-data

When you stop and remove the container (varc stop ctr-checkout-01 followed by varc rm ctr-checkout-01), varc overwrites materialized secret files with zeros before unlinking the isolated rootfs.


4. Run an Unpacked Directory in an Ephemeral Rootless Sandbox

When testing a local binary or dynamically linked tool without building a .varc image first, use varc sandbox (alias varc jail):

POWERSHELL
# Scratch sandbox (isolated rootfs containing only the target directory and explicit library mounts)
varc sandbox ./examples/dynamic-sandbox `
  --id sbx-dyn-01 `
  --mode scratch `
  --tier strict-compute `
  --seccomp enforce `
  --net none `
  --cmd "./bin/app --self-test" `
  --data-dir ./varc-data

5. Profile System Calls in Monitor Mode and Lock an Enforce BPF Filter

Instead of hand-writing brittle seccomp JSON profiles, start a workload in monitor mode, feed observed system calls from staging integration tests, and lock the container into kernel enforce mode:

POWERSHELL
# Record observed staging syscalls against the network-service baseline and lock Enforce BPF
varc policy-learn `
  --container ctr-checkout-01 `
  --tier network-service `
  --syscalls "read,write,openat,close,socket,bind,listen,accept4,epoll_ctl,epoll_wait,futex,clock_gettime" `
  --data-dir ./varc-data

6. Configure Zero-Root Virtual Networks and .varc Service DNS

Deploy a multi-service stack manifest (varc.conf) to automatically allocate deterministic 127.64.x.y loopback Virtual IPs and .varc / .vgate service discovery domains:

POWERSHELL
# Deploy a multi-service stack
varc up -f ./examples/postgres-ha-stack/varc.conf --data-dir ./varc-data

# Inspect allocated 127.64.x.y VIPs, .varc/.vgate DNS records, and synthesized hosts entries
varc net --data-dir ./varc-data
varc net --hosts --data-dir ./varc-data

7. Manage Copy-on-Write Persistent Volumes and Snapshots

Capture deduplicated CoW snapshots before schema migrations, convert chunk granularity for large database/model files, and compute delta replication plans:

POWERSHELL
# Capture a 16 KB chunked CoW snapshot into the Packed CAS Arena
varc volume snapshot orders-db `
  --dir ./examples/hello-service `
  --mode merkle_chunk_stream `
  --chunk-kb 16 `
  --data-dir ./varc-data

# Re-chunk an existing volume to 64 KB blocks for sequential I/O workloads
varc volume convert orders-db --dir ./examples/hello-service --chunk-kb 64 --data-dir ./varc-data

# Inspect delta transfer requirements and restore to a target directory
varc volume sync-plan orders-db --data-dir ./varc-data
varc volume restore orders-db --target ./restored-orders-db --data-dir ./varc-data

8. Authenticate and Operate the Web Studio Control Plane

Start varc serve and open http://127.0.0.1:8460/ui/auth to establish an authenticated operator session:

varc Auth & Identity Workspace

  1. Paste the 256-bit node API token (from <data_dir>/keys/api.token or VARC_API_TOKEN) into Node API Token.
  2. Select your required operational scopes (varc:runtime:run, varc:seccomp:lock, varc:stack:deploy, varc:appliance:sign) and click Sign In & Establish Session.
  3. Switch to Developer Portal (/ui/portal) -> Rootless Containers & VIPs to inspect live container statuses, enforce/monitor seccomp modes, loopback VIPs, and .varc DNS records:

varc Active Rootless Containers & Loopback VIPs

User Guide

This guide explains varc core concepts, container and WebAssembly workload lifecycles, resource controls, declarative stack orchestration, and the 4-Workspace Web Studio interface.


1. Single-File .varc Bundles and Content-Addressable Storage

Traditional container workflows split images across dozens of compressed tar layers, registry manifests, and root-owned overlay filesystems. varc replaces layered tar archives with a deterministic single-file .varc container bundle:

  • Integrity & Provenance: Every bundle carries an IEEE CRC32 envelope checksum, per-file SHA-256 digests, a 4 KB chunked SHA-256 Merkle tree root, and an Ed25519 signature bound to a named signer identity.
  • Deduplicated CAS Materialization: When varc run or varc extract processes a bundle, verified chunks are stored once inside <data_dir>/cas/ and materialized into an isolated per-container root filesystem (<data_dir>/rootfs/<container_id>/) with sanitized permissions (0755 executables, 0644 regular files, zero setuid/setgid bits).
  • Trust Policies:
  • tofu (Trust On First Use, default for local development): Pins a newly encountered signer's Ed25519 public key on first verification and rejects any subsequent key mismatch for that signer ID.
  • strict (recommended for production): Requires the bundle's signer ID and public key to be pre-pinned via varc keygen or varc trust add.

2. Workload Kinds and Lifecycle Management

varc supports two first-class workload kinds under a unified CLI and REST API:

Workload Kind Target Platform Execution Backend Primary Use Case
os_container linux/amd64, linux/arm64 linux-rootless-ns on Linux; wsl2-linux-bridge on Windows Microservices, databases, network proxies, CLI batch workers, OCI imports.
wasm_vvm wasm32/wasm32 vvm-wasm3 (WebAssembly 3.0 / WASI 0.3) Sub-millisecond cold-start functions, user-defined database/analytics UDFs, multi-tenant plugins.

Container Lifecycle States

POWERSHELL
# Inspect container metadata, rootfs path, VIP, and resource quotas
varc inspect ctr-hello-01 --data-dir ./varc-data

# Read ring-buffered stdout/stderr logs
varc logs ctr-hello-01 --tail 100 --data-dir ./varc-data

# Execute a diagnostic command inside the container context
varc exec ctr-hello-01 ./bin/hello-service --health --data-dir ./varc-data

# Pause, resume, restart, stop, and cleanly remove a container
varc pause ctr-hello-01 --data-dir ./varc-data
varc resume ctr-hello-01 --data-dir ./varc-data
varc restart ctr-hello-01 --data-dir ./varc-data
varc stop ctr-hello-01 --data-dir ./varc-data
varc rm ctr-hello-01 --data-dir ./varc-data

WebAssembly 4 KB Copy-on-Write Checkpoints

For wasm_vvm containers, varc wasm-snap captures page-granular (4 KB) linear-memory snapshots directly into the node CAS arena so warm instances can be restored without re-running initialization:

POWERSHELL
varc wasm-snap ctr-wasm-udf-01 --pages 8 --data-dir ./varc-data

3. Resource Quotas and Isolation Boundaries

Every container enforces explicit CPU, memory, process-count, filesystem, and network boundaries:

  • CPU & Memory Quotas: Configured at pack time (--cpu <millicores>, --memory <mb>) or per-service in varc.conf (cpu_millicores, memory_max_mb, pids_max). On Linux cgroups v2 hosts, varc maps these directly to cpu.max, memory.max, and pids.max.
  • Zero Implicit Host Mounts: Unlike desktop container wrappers that bind-mount $HOME or host credential sockets by default, varc sets expose_host_home = false unconditionally and rejects mounts targeting sensitive host paths (host root, etc, proc, sys, dev, root, var/run, ~/.ssh).
  • Telemetry & Stats: Inspect live per-container CPU millicores, memory usage, and cluster capacity headroom with varc stats:
POWERSHELL
varc stats --data-dir ./varc-data
varc stats --json --data-dir ./varc-data

4. Declarative Stacks, Cron/Batch Jobs, and Autoscaling

A single varc.conf file declares services, persistent volumes, scheduled Cron or parallel Batch jobs, and horizontal autoscaling rules.

POWERSHELL
# Reconcile a declarative stack
varc up -f ./examples/ecommerce-stack/varc.conf --data-dir ./varc-data

# Scale a specific service horizontally
varc scale commerce/checkout --replicas 4 --data-dir ./varc-data

# List and manually trigger scheduled Cron/Batch jobs
varc jobs --data-dir ./varc-data
varc job-run nightly-settlement --data-dir ./varc-data

# Evaluate horizontal autoscale policy against observed metrics
varc autoscale commerce/checkout --cpu 82 --memory 65 --rps 420 --data-dir ./varc-data

# Instant 1-second rollback to previous healthy stack & volume snapshot revision
varc rollback commerce --data-dir ./varc-data

5. Navigating the 4-Workspace Web Studio

varc serve hosts a zero-dependency Web Studio divided into four role-focused workspaces:

Workspace 1: Auth & Identity (/ui/auth)

Authenticate with your 256-bit node API token or OIDC provider, select granular session scopes using removable multi-select chips, inspect keyless Ed25519 bundle signing settings, and verify active rootless UID/GID namespace mappings.

Workspace 2: Developer & Application Portal (/ui/portal)

Browse registered .varc container and Wasm bundles with their 4 KB Merkle roots, transition containers from monitor learning mode into enforce BPF mode, and inspect active containers alongside their 127.64.x.y loopback VIPs:

varc Developer Portal — Registered Bundles

Workspace 3: Stack, Rollback & Jobs Operations (/ui/delegated)

Monitor WAL-backed multi-service stack revisions, trigger 1-Click Rollback across containers and CoW volume snapshots, trigger Cron/Batch jobs on demand, and review horizontal autoscaling policies:

varc Stack & Jobs Operations Workspace

Workspace 4: Fleet, VNet & Security Administration (/ui/admin)

Deploy turnkey trustnode.sh appliance suites (security, core, data, ai), inspect the zero-root 127.64.x.y VNet DNS mesh, monitor persistent volume replication states, and audit the SHA-256 hash-chained event ledger in either Light Mode or Dark Mode (Dark / Light toggle in the top header).

Administrator Guide

This guide covers node bootstrap, authentication hardening, cryptographic signer governance, admission policy enforcement, multi-node cluster management, storage compaction, and tamper-evident audit verification for varc operators.


1. Node Data Directory Layout and Bootstrap Security

When varc initializes a node (--data-dir <path>, default data/varc), it creates a structured, self-contained state hierarchy:

TEXT
<data_dir>/
  commit.log              # 32-byte VPRV IEEE CRC32 Write-Ahead Log
  state.snap              # Atomic TSV checkpoint snapshot
  audit-archive.log       # Rotated SHA-256 hash-chained RFC 5424 audit segments
  keys/
    master.kek            # 256-bit Node Key-Encryption Key (0600 permissions)
    api.token             # 256-bit Bootstrap Control Plane API Token (0600 permissions)
    <signer>.ed25519.enc  # AES-256-GCM KEK-sealed Ed25519 private signing keys
  cas/
    chunks.pack           # Contiguous Packed Content-Addressable Storage arena
    chunks.idx            # SHA-256 -> (offset, length) chunk index
  rootfs/
    <container_id>/       # Per-container isolated root filesystem & zeroizable secrets
  seccomp/
    <container_id>.seccomp.conf  # Locked Monitor -> Enforce syscall profiles
  volumes/
    snaps/<snap_id>.snap.tsv     # Per-revision CoW volume snapshot manifests

2. Control Plane Authentication and Session Governance

All mutating and state-reading /api/v1/* endpoints require authentication via either:

  1. Bearer API Token: Set VARC_API_TOKEN in the service environment (minimum 32 hex/ASCII characters recommended) or read the auto-generated 256-bit token at <data_dir>/keys/api.token.
  2. HttpOnly Session Cookie: Established via POST /api/v1/auth/session (used by /ui/auth) with mandatory CSRF header enforcement (X-Varc-Requested-With: 1) and SameSite=Strict.
POWERSHELL
# Start Control Plane bound strictly to loopback or a private management interface
$env:VARC_API_TOKEN = "d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3"
varc serve --listen 127.0.0.1:8460 --data-dir ./data

3. Admission Policy Enforcement and Trusted Signers

Pinning and Revoking Ed25519 Bundle Signers

In production clusters, enforce --trust strict so only bundles signed by explicitly pinned release keys can execute:

POWERSHELL
# Pin an offline CI/CD release signing public key
varc trust add `
  --signer prod-release-ca `
  --pubkey 9261829d380df711264bb9feef978c77a04cb4177899a56e30673f9cdb5bd81e `
  --data-dir ./data

# Audit currently trusted signers and trust sources
varc trust list --data-dir ./data

# Immediately revoke a retired or compromised signing identity
varc trust rm prod-release-ca --data-dir ./data

Baseline Seccomp-BPF Tiers

Every OS container is assigned a baseline syscall tier combined with an unconditional 41-syscall kernel deny list:

Tier Baseline Syscalls Intended Workloads
strict-compute 24 Pure compute workers, parsers, batch transformers (net=none).
crypto-appliance 31 Key management, signing authorities, token issuers (getrandom, mlock).
network-service 47 HTTP/gRPC APIs, reverse proxies, connection poolers (socket, epoll_wait, accept4).
filesystem-worker 63 Databases, CoW volume replicators, search indexers (fsync, fdatasync, renameat2).

4. Zero-Root VNet Mesh and Multi-Node Cluster Scheduling

varc assigns each node a /24 slice inside 127.64.<subnet>.0/24 and resolves .varc and .vgate service domains without requiring root privileges or kernel bridge modules:

varc Fleet Admin — Zero-Root 127.64.x.y Loopback VIP & DNS Mesh

Managing Cluster Nodes

Register worker nodes with CPU, memory, subnet, and topology zone labels for anti-affinity bin-packing scheduling:

POWERSHELL
# Register two availability-zone worker nodes
varc node join node-east-01 --addr 10.20.1.11:8460 --subnet 11 --cpu 16000 --memory 32768 --labels zone=us-east-a,tier=compute --data-dir ./data
varc node join node-east-02 --addr 10.20.1.12:8460 --subnet 12 --cpu 16000 --memory 32768 --labels zone=us-east-b,tier=compute --data-dir ./data

# Inspect node capacity and health
varc node list --data-dir ./data

# Cordoning/draining a node prior to OS patching
varc node drain node-east-01 --data-dir ./data
varc node rm node-east-01 --data-dir ./data

5. Storage Compaction, CAS Garbage Collection, and Audit Verification

Run routine Day-2 storage maintenance and cryptographic audit verification via varc system:

POWERSHELL
# 1. Compact commit.log into an atomic state.snap checkpoint and truncate WAL
varc system checkpoint --data-dir ./data

# 2. Run streaming Tri-Root Mark-and-Sweep CAS Garbage Collection
#    (preserves chunks referenced by active images, retained stack revisions, and volume snapshots)
varc system gc --data-dir ./data

# 3. Cryptographically verify the SHA-256 hash-chained RFC 5424 audit ledger
varc system audit-verify --data-dir ./data

# 4. Stream recent security and lifecycle audit events
varc events --tail 50 --data-dir ./data

varc Fleet Admin Dark Mode — SHA-256 Hash-Chained Audit Ledger & SOAR Quarantine


6. Upgrades, Backup, and Disaster Recovery

  1. Pre-Upgrade Checkpoint: Run varc system checkpoint and capture fresh volume snapshots (varc volume snapshot <vol_id> --dir <mount_path> --mode merkle_chunk_stream).
  2. Atomic Binary Upgrade: Because varc is a single static-style executable with zero background daemon lock-in, replace the varc binary in place and verify varc version.
  3. Post-Upgrade Verification: Run varc system audit-verify and varc health <stack_name> to confirm WAL state recovery, intact audit hash chains, and healthy service VIPs.

Operations & Use Cases

This guide presents production deployment architectures, end-to-end configuration manifests, REST API automation workflows, and incident response runbooks for varc.


Use Case 1: Stateful HA PostgreSQL + Wasm Analytics Stack with 1-Second Rollback

Organizations running transactional PostgreSQL clusters alongside low-latency analytics functions often struggle to coordinate schema upgrades, connection pooler updates, and data volume snapshots. With varc, a single declarative varc.conf manages OS containers, vvm WebAssembly 3.0 UDF workers, CoW persistent volumes, and health-gated rollback.

Declarative Stack Manifest (postgres-ha.varc.conf)

INI
stack_name = postgres-ha-stack
version = 16.4.0

[volume.pg-heap]
mount_path = ./volumes/pgdata
quota_mb = 16384
chunk_size_kb = 64
replication_mode = wal_delta_sync

[service.pg-primary]
image = postgres-varc:16.4.0
replicas = 1
vip = 127.64.4.10
port = 5432
seccomp_mode = enforce
seccomp_tier = filesystem-worker
volume = pg-heap:./volumes/pgdata
cpu_millicores = 4000
memory_max_mb = 8192

[service.pg-bouncer]
image = pgbouncer-varc:1.22.0
replicas = 2
vip = 127.64.4.11
port = 6432
seccomp_mode = enforce
seccomp_tier = network-service
depends_on = pg-primary

[service.wasm-analytics-udf]
image = udf-rollup-wasm:1.0.0
workload_kind = wasm_vvm
replicas = 2
vip = 127.64.4.12
port = 8090
seccomp_mode = enforce
seccomp_tier = strict-compute

[job.nightly-wal-verify]
image = pg-verify-job:1.0.0
kind = cron
schedule = "0 2 * * *"
concurrency = forbid

Deployment, Health Probing, and Automated Rollback

POWERSHELL
# Apply the stack (automatically snapshots CoW volumes prior to revision rollout)
varc up -f ./postgres-ha.varc.conf --data-dir ./data

# Probe TCP health across stack VIPs and auto-rollback if any replica fails readiness
varc health postgres-ha-stack --probe-tcp --auto-rollback --data-dir ./data

# Or trigger explicit rollback to a specific historical revision
varc rollback postgres-ha-stack --revision 1 --data-dir ./data

Use Case 2: Air-Gapped & Edge Single-File Appliance Delivery

Remote industrial gateways, defense enclaves, and retail edge nodes frequently lack outbound container registry connectivity and prohibit root daemons. varc enables deterministic single-file delivery over optical diodes or USB media:

  1. Build Zone (Connected CI):
POWERSHELL
   varc keygen --signer edge-release-2026 --data-dir ./ci-state
   varc pack --name edge-telemetry --version 3.1.0 --dir ./build/rootfs `
     --seccomp enforce --tier network-service --signer edge-release-2026 `
     --out ./edge-telemetry-3.1.0.varc --data-dir ./ci-state
  1. Air-Gapped Edge Host (Zero Network Access):
POWERSHELL
   # Pin the public key once during host provisioning
   varc trust add --signer edge-release-2026 --pubkey <64-hex-ed25519-pubkey> --data-dir ./data

   # Offline cryptographic verification (CRC32 + 4 KB Merkle + Ed25519)
   varc verify ./edge-telemetry-3.1.0.varc

   # Launch unprivileged with strict trust enforcement
   varc run ./edge-telemetry-3.1.0.varc --trust strict --seccomp enforce --data-dir ./data

Use Case 3: Turnkey trustnode.sh Security & Infrastructure Fleet

varc includes built-in appliance packaging and one-command suite orchestration for the 11 trustnode.sh infrastructure services (vca, vwarden, vsight, vgate, vvm, vprevail, vstore, vft, vkbm, vllm, vsite):

POWERSHELL
# Package an individual appliance with deterministic VIP and seccomp tier defaults
varc appliance --project vgate --out ./bundles/vgate.varc --data-dir ./data

# Deploy the security suite (vca, vwarden, vsight on 127.64.0.11..13)
varc trustnode-up --suite security --data-dir ./data

# Or deploy via the authenticated Control Plane REST API
curl -sS -X POST http://127.0.0.1:8460/api/v1/stacks/apply \
  -H "Authorization: Bearer $VARC_API_TOKEN" \
  -H "X-Varc-Requested-With: 1" \
  -H "Content-Type: application/json" \
  -d '{"suites":"security,core"}'

Use Case 4: Private AI & Knowledge Retrieval Appliance (ai-rag-stack)

Teams deploying internal retrieval-augmented generation (RAG) pipelines need strict isolation between public ingress, vector/knowledge indexing, and compute-heavy model inference—without relying on external cloud registries or privileged container daemons. The examples/ai-rag-appliance/varc.conf blueprint pairs vgate-ingress, vkbm-index, and vllm-inference over the 127.64.x.y loopback mesh:

  • Large-Chunk Model Weights (512 KB): The model-weights volume uses 512 KB CoW chunks (quota_mb = 32768, merkle_chunk_stream) so multi-gigabyte model files deduplicate and stream with minimal index overhead.
  • Tiered Seccomp Isolation: vgate-ingress runs under network-service, vkbm-index under filesystem-worker, and vllm-inference under strict-compute.
  • Scheduled Index Compaction & RPS Autoscaling: A 6-hour Cron job (30 */6 * * *) compacts knowledge indexes while vllm-inference scales between 1 and 6 replicas based on CPU (75%) and request rate (50 RPS per replica).
POWERSHELL
# Deploy the AI & Knowledge Retrieval stack
varc up -f ./examples/ai-rag-appliance/varc.conf --data-dir ./data

# Verify VNet VIPs (.varc / .vgate DNS) and volume chunk geometry
varc net --hosts --data-dir ./data
varc volumes --data-dir ./data

# Evaluate inference autoscaling under load (e.g., 82% CPU, 240 RPS)
varc autoscale ai-rag-stack/vllm-inference --cpu 82 --memory 68 --rps 240 --data-dir ./data

Use Case 5: E-Commerce Microservices with Secrets, Batch Jobs & Safe Rollback

Multi-service transactional applications must coordinate encrypted API credentials, stateful order storage, background batch reindexing, and instant rollback when a release degrades readiness checks. The examples/ecommerce-stack/varc.conf manifest demonstrates this full lifecycle:

  1. Seal Runtime Credentials First:
POWERSHELL
   varc secret set db_password --value "prod-orders-db-pass" --data-dir ./data
   varc secret set stripe_webhook_secret --value "whsec_live_example" --data-dir ./data
  1. Deploy the Stack (edge-proxy, checkout-api, orders-worker):
POWERSHELL
   # Applies 3 services, 16 KB-chunk orders-data volume, nightly cron, and 4-way batch reindex
   varc up -f ./examples/ecommerce-stack/varc.conf --data-dir ./data

   # Inspect running containers and health probe status across 127.64.2.10..12
   varc ps --data-dir ./data
   varc health ecommerce-stack --probe-tcp --data-dir ./data
  1. Roll Back Atomically on Regression:
POWERSHELL
   # Revert containers, secrets bindings, and orders-data volume snapshot in one command
   varc rollback ecommerce-stack --data-dir ./data

Use Case 6: Ephemeral Scratch Sandboxing for Untrusted Binaries & Plugins

When you need to run a third-party CLI tool, vendor diagnostic binary, or CI build plugin without packing a .varc image—and without exposing host /usr, /lib, or home directories—use varc sandbox in --mode scratch. Using examples/dynamic-sandbox/:

BASH
# Run an unpacked app with explicitly staged vendor libraries and zero network access
varc sandbox --id sbx-vendor-audit --mode scratch \
  --dir ./examples/dynamic-sandbox/app \
  --lib-dir ./examples/dynamic-sandbox/vendor-libs \
  --lib-path ./lib:./lib64:./vendor/lib \
  --seccomp monitor --tier strict-compute \
  --net none \
  -- ./bin/worker.sh

# Inspect sandbox telemetry and exit status as JSON
varc sandbox --id sbx-vendor-audit --mode scratch \
  --dir ./examples/dynamic-sandbox/app \
  --lib-dir ./examples/dynamic-sandbox/vendor-libs \
  --json -- ./bin/worker.sh

Once the sandbox run finishes, any temporary rootfs state is discarded, leaving the host filesystem untouched.


Use Case 7: Hybrid Native + WebAssembly 3.0 (vvm) Edge Workers

For latency-sensitive request filters, webhook transformers, or untrusted tenant plugins, you can package WebAssembly 3.0 / WASI 0.3 modules as first-class .varc bundles and run them alongside native OS containers:

POWERSHELL
# 1. Package a Wasm 3.0 module into a signed .varc bundle
varc pack `
  --name webhook-filter `
  --version 1.0.0 `
  --kind wasm_vvm `
  --dir ./build/wasm-filter `
  --entrypoint ./filter.wasm `
  --tier strict-compute `
  --seccomp enforce `
  --vip 127.64.5.20 `
  --signer prod-release-ca `
  --out ./bundles/webhook-filter-1.0.0.varc `
  --data-dir ./data

# 2. Verify and launch inside the vvm CoW sandbox
varc verify ./bundles/webhook-filter-1.0.0.varc
varc run ./bundles/webhook-filter-1.0.0.varc --id ctr-wasm-filter-01 --data-dir ./data

Because vvm isolates linear memory with 4 KB Copy-on-Write pages, multiple tenant invocations can be snapshotted and restored in microseconds without spinning up separate OS namespaces per request.


Use Case 8: Live & Air-Gapped Host Migration for OS Containers (varc migrate & .varc-mig)

When draining a host for kernel maintenance or rebalancing stateful services across nodes, varc supports both live HTTP/1.1 node-to-node migration and offline/air-gapped .varc-mig staged bundle migration. Both paths enforce 3-pass pre-copy volume Merkle delta sync, hybrid AES-256-GCM secret re-wrapping, .learn.tsv seccomp session continuity, and monotonic migration_epoch split-brain fencing.

Form A: One-Command Live HTTP/1.1 Migration (varc migrate <id> --to <node>)

When both nodes are reachable over the Control Plane API, run a single command (or POST /api/v1/migrations/live) to execute the entire flow—pre-condition checks, pre-drain hook, 3-pass pre-copy CAS delta sync, HTTP/1.1 transfer, vnet 500–2000 ms hold-buffer cutover, and source fencing:

POWERSHELL
# One-command live migration with a pre-drain hook
varc migrate ctr-checkout-01 `
  --to node-b `
  --target-addr 127.0.0.1:8470 `
  --pre-drain-hook "http://127.64.2.11:8080/drain" `
  --secrets pg_dsn,jwt_hmac_key `
  --volume-dir ./volumes/orders `
  --data-dir ./data

Or trigger the same one-shot live migration over HTTP:

BASH
curl -sS -X POST http://127.0.0.1:8460/api/v1/migrations/live \
  -H "Authorization: Bearer $VARC_API_TOKEN" \
  -H "X-Varc-Requested-With: 1" \
  -H "Content-Type: application/json" \
  -d '{"container_id":"ctr-checkout-01","target_node":"node-b","target_addr":"127.0.0.1:8470","pre_drain_hook":"signal:SIGUSR1","secrets":"pg_dsn,jwt_hmac_key"}'

Form B: Air-Gapped .varc-mig Staged Migration

For disconnected enclaves or shared-storage handoffs without direct node-to-node HTTP connectivity:

POWERSHELL
# 1. On Source Host: export signed .varc-mig bundle with re-wrapped secrets
varc migrate export ctr-checkout-01 `
  --to node-b `
  --out ./ctr-checkout-01.varc-mig `
  --volume-dir ./volumes/orders `
  --secrets pg_dsn,jwt_hmac_key `
  --target-pubkey <target-ed25519-pub-hex> `
  --data-dir ./data

# 2. On Target Host: verify CRC32 + Ed25519 + per-chunk SHA-256 and commit at epoch+1
varc migrate import ./ctr-checkout-01.varc-mig `
  --trusted-pubkey <source-ed25519-pub-hex> `
  --data-dir ./data

# 3. On Source Host: fence old instance and zeroize local secrets
varc migrate fence ctr-checkout-01 --migration <mig-id> --epoch 2 --data-dir ./data

Use Case 9: Live Cross-OS & Cross-Architecture wasm_vvm Migration (.varc-ckpt)

Unlike native OS binaries (os_container), which require matching CPU architectures and compatible Linux/WSL2 hosts, wasm_vvm sandboxes execute portable WebAssembly 3.0 bytecode. When varc migrates a wasm_vvm workload (for example, moving an edge worker from a linux/x86_64 node to a macos/arm64 node), it suspends execution at a cooperative safe point and emits a signed .varc-ckpt (VARCCKPT) checkpoint envelope:

  1. Pre-Copy 4 KB Dirty Pages: Only 4 KB linear-memory pages modified since the baseline snapshot are included, verified per page via SHA-256.
  2. Deterministic Execution State: Globals, indirect-call table slots, call frames, remaining fuel quota, instruction pointer, and virtualized WASI 0.3 file descriptors (with seek cursors) are serialized alongside the memory delta.
  3. Sub-Second Resume: The target vvm runtime verifies the Ed25519 signature and aggregate Merkle root, patches the 4 KB dirty pages, and resumes execution from the exact safe point.

Migration Best Practices, Pre/Post Conditions & Gotchas

Pre-Conditions (Checked Before Migration Starts)

  • Source Container State: The container must be running or paused, and its migration_state must be none (not already migrating_out or fenced).
  • Target Node Readiness & Headroom: In live cluster mode, the target node must be ready (not draining, cordoned, or offline) with enough available CPU millicores and memory MB.
  • OS & Architecture Compatibility: os_container workloads require matching CPU architecture and compatible OS (linux <-> wsl2). wasm_vvm workloads can migrate across any OS and CPU architecture.
  • Trust & Secret Keying: For air-gapped .varc-mig transfers, pin the source signer's Ed25519 public key (--trusted-pubkey) on the target and pass --target-pubkey during export so secrets are wrapped specifically for the target node.

Post-Conditions (Guaranteed After Successful Migration)

  • Target Active at epoch + 1: The target container is running with migration_state = none and migration_epoch = epoch + 1.
  • Source Fenced & Zeroized: The source container is stopped, migration_state = fenced at epoch + 1, and its materialized secrets are zeroized. Any partitioned node reconnecting with a stale epoch self-fences automatically.
  • Audit & Continuity Preserved: seccomp monitor-mode .learn.tsv sessions, CAS delta chunks, and SHA-256 hash-chained audit events are intact on both nodes.

Best Practices & Common Gotchas

  • Use a Pre-Drain Hook (--pre-drain-hook) for Stateful Apps: Point --pre-drain-hook to a loopback endpoint (http://127.64.x.y:port/drain) or signal (signal:SIGUSR1) so databases and workers flush write buffers before the final delta pass. Non-loopback HTTP hooks are blocked by the built-in SSRF guard.
  • Watch for Write-Heavy Churn (--force-pause): varc caps pre-copy at 3 passes. If a workload mutates volume chunks faster than they can sync, varc aborts safely without touching the running container. Use --force-pause during a maintenance window if you want varc to pause the workload and force the final delta.
  • Open TCP Connections on os_container: varc stays 100% rootless and zero-dependency (no CRIU), so vnet's 500–2000 ms hold buffer buffers new connections during cutover while existing connections drain. Place vgate ingress in front of services if clients need automatic retry on in-flight HTTP requests.
  • Use vprevail Quorum Fencing for Multi-Node HA: For 3+ node clusters, configure VprevailQuorumFenceProvider so lease acquisition requires a strict majority (N/2 + 1), preventing split-brain even during asymmetric network partitions.

Production Day-2 Incident Runbooks

Runbook A: Immediate SOAR Container Quarantine

When an anomaly detector (such as vsight) flags suspicious egress or unexpected behavior in a running workload, quarantine the container without destroying forensic rootfs or memory state:

BASH
curl -sS -X POST http://127.0.0.1:8460/api/v1/containers/quarantine \
  -H "Authorization: Bearer $VARC_API_TOKEN" \
  -H "X-Varc-Requested-With: 1" \
  -H "Content-Type: application/json" \
  -d '{"container_id":"ctr-commerce-checkout-1"}'

Quarantine atomically pauses the container execution state, revokes its 127.64.x.y virtual network peer routes, and appends a signed container.quarantine event to the SHA-256 hash-chained audit log.

Runbook B: Live Traffic Spike & Horizontal Autoscale Reconciliation

BASH
# Query real-time CPU, memory, and autoscale telemetry
curl -sS http://127.0.0.1:8460/api/v1/stats \
  -H "Authorization: Bearer $VARC_API_TOKEN"

# Trigger policy-based horizontal scale evaluation via CLI
varc autoscale commerce/checkout --cpu 88 --memory 70 --rps 650 --data-dir ./data

Runbook C: Corrupted Disk Tail Recovery & Audit Verification

If a host suffers an unclean power loss mid-deployment:

  1. Run varc system audit-verify --data-dir ./data. During store open, varc validates every 32-byte VPRV IEEE CRC32 WAL frame and automatically truncates any incomplete torn tail frame cleanly to the last committed transaction boundary.
  2. Run varc system checkpoint --data-dir ./data to persist a fresh state.snap image.
  3. Run varc ps --data-dir ./data and varc health <stack_name> --probe-tcp to confirm service availability.

Configuration & CLI Reference

This reference documents all varc command-line subcommands, flags, environment variables, varc.conf declarative stack directives, and HTTP/1.1 Control Plane REST API endpoints.


1. Global Node Flags and Environment Variables

All stateful CLI subcommands accept the following node flags:

Flag Default Description
--data-dir <path> data/varc Path to the node state directory containing WAL, CAS arena, keys, rootfs, and volume snapshots.
--listen <host:port> 127.0.0.1:8460 TCP bind address for varc serve and node discovery metadata.
--json / -j false Emit structured JSON output on supported inspection and listing commands.

Environment Variables

Variable Purpose
VARC_API_TOKEN Overrides the on-disk <data_dir>/keys/api.token Bearer token used by varc serve for HTTP API and Web Studio authentication.
VARC_DATA_DIR Optional default override for --data-dir when not explicitly passed on the command line.
VARC_LISTEN_ADDR Optional default override for --listen (127.0.0.1:8460).

2. Image, Signing & Appliance Subcommands

Subcommand Syntax & Key Options Description
pack varc pack --name <name> --version <ver> --dir <src_dir> [--out <file.varc>] [--kind os_container|wasm_vvm] [--entrypoint <path>] [--seccomp monitor|enforce] [--tier <tier>] [--net isolated|vnet|none] [--vip <127.64.x.y>] [--cpu <m>] [--memory <mb>] [--signer <id>] Package a directory into a signed .varc single-file container or Wasm bundle.
import varc import --oci <oci_dir> --name <name> --version <ver> [--out <file.varc>] Import an unpacked OCI layout (config.json + rootfs/) into a signed .varc bundle.
appliance varc appliance --project <vca|vwarden|vsight|vgate|vvm|...> [--dir <src_dir>] [--out <file.varc>] Package a trustnode.sh appliance with preset VIP and seccomp tier defaults.
inspect varc inspect <file.varc | container_id | image_id> [--json] Display bundle manifest/signature details or registered container/image state.
verify varc verify <file.varc> Verify 64-byte header framing, IEEE CRC32, 4 KB Merkle tree root, and Ed25519 signature.
extract varc extract <file.varc> [--cas <dir>] [--rootfs <dir>] Materialize verified .varc files into a CAS directory and isolated rootfs.
images varc images [--json] List registered .varc bundles, workload kinds, signers, sizes, and Merkle roots.
rmi varc rmi <image_id_or_name> [--force] Remove a registered image record from the node catalog.
keygen varc keygen [--signer <id>] Generate or load an AES-256-GCM KEK-sealed Ed25519 signing keypair and pin its public key.
trust varc trust <list | add --signer <id> --pubkey <hex> | rm <id>> List, pin, or revoke trusted Ed25519 bundle signers.

3. Rootless Runtime, Sandbox & Policy Subcommands

Subcommand Syntax & Key Options Description
run varc run <file.varc> [--id <cid>] [--name <name>] [--stack <stack>] [--trust tofu|strict] [--seccomp monitor|enforce] [--net isolated|vnet|none] [--vip <ip>] [--secret <s1,s2>] [--env <K=V,...>] [--exec] Verify, extract into CAS/rootfs, compile BPF policy, and launch a rootless container.
sandbox / jail varc sandbox <dir_or_bin> [--id <id>] [--mode scratch|ro-system] [--tier <tier>] [--seccomp monitor|enforce] [--net none|isolated] [--lib-dir <path>] [--cmd "<args>"] Execute an unpacked binary or directory inside an ephemeral rootless namespace sandbox.
ps varc ps [--json] List registered containers, statuses, seccomp modes, loopback VIPs, and runtime backends.
stop / pause / resume / restart varc <stop|pause|resume|restart> <container_id> Transition container execution state and update durable WAL state.
rm varc rm <container_id> [--force] Remove a stopped container, zeroize materialized secrets, and delete its isolated rootfs.
logs varc logs <container_id> [--tail <lines>] Read ring-buffered container standard output and error streams.
exec varc exec <container_id> [--live] <command...> Execute a diagnostic command inside a running container context.
wasm-snap varc wasm-snap <container_id> [--pages <1..64>] Capture a 4 KB CoW linear-memory checkpoint for a wasm_vvm sandbox.
policy-learn varc policy-learn --container <cid> [--tier <tier>] --syscalls "<s1,s2,...>" Record legitimate syscalls in Monitor mode, block high-risk calls, and lock an Enforce BPF profile.

4. Orchestrator, Volume, Cluster & System Subcommands

Subcommand Syntax & Key Options Description
up varc up -f <path/to/varc.conf> Reconcile a declarative stack manifest, volumes, DNS records, jobs, and autoscale policies.
down varc down <stack_name> Stop all containers belonging to a stack and zeroize mounted secrets.
scale varc scale <stack>/<service> --replicas <n> Horizontally scale service replicas within a deployed stack.
rollback varc rollback <stack_name> [--revision <n>] Roll back stack containers and CoW persistent volume snapshots to a prior healthy revision.
health varc health <stack_name> [--probe-tcp] [--auto-rollback] Probe service readiness (with SSRF guard) and optionally auto-rollback unhealthy revisions.
stacks varc stacks [--json] List deployed stack revisions and active container memberships.
jobs / job-run varc jobs [--json] / varc job-run <job_id> List registered Cron/Batch jobs or trigger immediate job execution.
volumes / volume varc volume <list | snapshot <id> --dir <d> [--mode <m>] [--chunk-kb <k>] | convert <id> --dir <d> --chunk-kb <k> | restore <id> --target <d> | sync-plan <id>> Manage CoW persistent volumes, Packed CAS chunk granularity, delta plans, and restores.
secret varc secret <list | set <name> --value <v|-> | get <name> | rm <name>> Manage NIST SP 800-38D AES-256-GCM encrypted runtime secrets.
net / dns varc net [--hosts] [--json] Display allocated 127.64.x.y loopback VIPs, .varc/.vgate DNS records, or etc/hosts blocks.
stats varc stats [--json] Display container CPU/memory telemetry, cluster capacity, and autoscale rules.
autoscale varc autoscale <stack>/<service> --cpu <pct> --memory <pct> --rps <n> Evaluate horizontal autoscaling thresholds and adjust replica counts.
node varc node <list | join <id> --addr <h:p> --subnet <n> --cpu <m> --memory <mb> [--labels <k=v>] | drain <id> | rm <id>> Manage multi-node cluster membership, VIP subnet slices, and scheduling state.
migrate varc migrate <<cid> --to <node> [--target-addr <h:p>] [--pre-drain-hook <hook>] [--force-pause] | export <cid> --to <node> --out <file.varc-mig> [--volume-dir <d>] [--secrets <s1,s2>] [--target-pubkey <hex>] [--force-pause] | import <file.varc-mig> [--trusted-pubkey <hex>] | fence <cid> --migration <id> --epoch <n>> Execute one-command live migration or export, import, and epoch-fence .varc-mig bundles.
trustnode-up varc trustnode-up [--suite security|core|data|ai|all] Deploy turnkey trustnode.sh infrastructure appliance suites.
system varc system <checkpoint | gc | audit-verify | events> Compact WAL snapshots, run Tri-Root CAS garbage collection, or verify SHA-256 audit chains.
events varc events [--tail <n>] [--json] Tail SHA-256 hash-chained RFC 5424 audit records.
serve varc serve [--listen <addr>] [--max-requests <n>] [--dry-run] Start the HTTP/1.1 Control Plane REST API and 4-Workspace Web Studio server.
openapi varc openapi Print the complete OpenAPI 3.1.0 JSON specification to stdout.
discovery varc discovery Emit JSON node capability and endpoint discovery metadata.
bench varc bench [--markdown] [--dir <temp_dir>] Run the 9-workload empirical performance benchmark suite.

5. Declarative varc.conf Configuration Schema

varc.conf uses a clean, deterministic INI/key-value section syntax with zero external parser dependencies:

INI
# Global stack metadata
stack_name = commerce
version = 2.1.0

# Persistent Copy-on-Write volume declaration
[volume.orders-data]
mount_path = ./volumes/orders
quota_mb = 4096
chunk_size_kb = 16
replication_mode = merkle_chunk_stream

# Service declaration (OS container or wasm_vvm)
[service.checkout]
image = checkout-api:2.1.0
workload_kind = os_container
replicas = 2
vip = 127.64.2.20
port = 8080
seccomp_mode = enforce
seccomp_tier = network-service
network_mode = vnet
cpu_millicores = 1000
memory_max_mb = 512
volume = orders-data:./volumes/orders
secrets = db_password,stripe_webhook_secret
depends_on = orders-db

# Scheduled Cron or Parallel Batch job
[job.nightly-ledger-sync]
image = ledger-worker:2.1.0
kind = cron
schedule = "30 1 * * *"
concurrency = forbid

# Policy-driven horizontal autoscaler
[autoscale.checkout]
min_replicas = 2
max_replicas = 8
target_cpu_percent = 75
target_memory_percent = 80
target_rps_per_replica = 250
cooldown_seconds = 60

6. HTTP/1.1 Control Plane REST API Endpoints

All /api/v1/* routes (except /healthz, /readyz, and /api/v1/auth/session) require Authorization: Bearer <token> (or an active varc_session cookie) and X-Varc-Requested-With: 1 on POST mutations.

Method Path Purpose
GET /healthz, /readyz Unauthenticated liveness and readiness probes (200 OK).
GET /openapi.json Full OpenAPI 3.1.0 Control Plane schema.
GET /ui/auth, /ui/portal, /ui/delegated, /ui/admin 4-Workspace Web Studio HTML5 Control Plane views.
POST /api/v1/auth/session Validate API token and issue HttpOnly; SameSite=Strict operator session cookie.
POST /api/v1/auth/logout Invalidate active operator session cookie.
GET /api/v1/images List registered .varc bundles and 4 KB Merkle roots.
GET /api/v1/containers List containers, statuses, seccomp modes, loopback VIPs, and DNS domains.
GET /api/v1/stacks List deployed stack revisions and container memberships.
GET /api/v1/jobs List registered Cron and Batch jobs with execution counters.
GET /api/v1/network List zero-root 127.64.x.y VIP allocations and .varc/.vgate DNS records.
GET /api/v1/volumes List persistent volumes, chunk sizes, replication modes, and latest snapshot IDs.
GET /api/v1/stats Retrieve container CPU/memory telemetry, cluster node headroom, and autoscale rules.
GET /api/v1/audit Retrieve SHA-256 hash-chained RFC 5424 security and lifecycle audit events.
POST /api/v1/seccomp/lock Lock a container's learned monitor syscall profile into enforce mode ({"container_id":"..."}).
POST /api/v1/stacks/apply Deploy one or more trustnode.sh appliance suites ({"suites":"security,core"}).
POST /api/v1/stacks/rollback Roll back a stack and its CoW volumes ({"stack_name":"...","target_revision":"0"}).
POST /api/v1/jobs/trigger Trigger immediate execution of a registered Cron/Batch job ({"job_id":"..."}).
POST /api/v1/containers/quarantine Atomically pause a container, isolate its VIP, and log a SOAR quarantine audit event ({"container_id":"..."}).
GET /api/v1/migrations List durable cross-host migration records, phases, and monotonic migration_epoch values.
POST /api/v1/migrations/export Run pre-flight checks, 3-pass pre-copy CAS delta sync, and export a signed .varc-mig payload.
POST /api/v1/migrations/import Verify .varc-mig, apply CAS deltas and wrapped secrets, and commit target container at epoch+1.
POST /api/v1/migrations/fence Fence a migrated source container at epoch+1 and zeroize its materialized secrets.
POST /api/v1/migrations/live Execute one-command live migration (pre-conditions, pre-drain hook, 3-pass pre-copy, HTTP stream, and source fence).

Performance & Sizing Guide

varc includes a built-in, deterministic 9-workload benchmark harness (varc bench) that measures cryptographic secret sealing, 4 KB SHA-256 Merkle tree reduction, single-file .varc bundle signing and verification, seccomp-bpf compilation, VPRV Write-Ahead Log replay, Packed CAS Copy-on-Write volume streaming, and declarative stack rollback.


1. Running the Built-In Benchmark Suite

Run the empirical benchmark suite on any host to measure local CPU, memory, and storage performance:

POWERSHELL
# Console summary table
varc bench

# GitHub-flavored Markdown report for release validation or capacity baselining
varc bench --markdown

# Benchmark against a specific storage mount (e.g., NVMe production volume)
varc bench --dir ./data/bench-tmp --markdown

2. Empirical 9-Workload Benchmark Baseline

The table below records measured production-build (-prod) throughput, bandwidth, and average per-operation latency across all nine core runtime and control-plane hot paths:

Workload Operations Elapsed (ms) Throughput (ops/sec) Bandwidth (MB/s) Avg Latency (us) Architectural Design Characteristic
AES-256-GCM Seal & Unseal (4 KB) 500 85.22 ms 5,867.0 ops/s 22.92 MB/s 170.44 us Precomputed expanded AES-256 key schedule, unique 96-bit IVs, stack-allocated 16-byte cipher blocks, and branchless GF(2^128) authentication.
.varc 4 KB Merkle Tree (256 KB / 64 Chunks) 200 359.67 ms 556.1 ops/s 139.02 MB/s 1,798.34 us Contiguous flat digest arena with in-place binary tree reduction and zero intermediate slice cloning.
.varc Bundle Pack & Ed25519 Sign (64 KB) 100 458.09 ms 218.3 ops/s 13.83 MB/s 4,580.92 us Single-pass envelope serialization, IEEE CRC32 framing, 4 KB SHA-256 Merkle root, and Ed25519 signing.
.varc Bundle Unpack & Full Verify (64 KB) 200 434.84 ms 459.9 ops/s 29.14 MB/s 2,174.18 us 6-stage admission check: magic bytes, bounds guard, CRC32, per-file SHA-256, Merkle root, and constant-time Ed25519 verify.
Seccomp-BPF Learn & Filter Compile 2,000 56.99 ms 35,094.9 ops/s 49.00 MB/s 28.49 us Zero-allocation syscall ABI number dispatch, O(1) 41-syscall high-risk deny check, and pre-sized BPF filter emission.
VPRV 32B CRC32 WAL Append, Snap & Replay 1,000 36.80 ms 27,170.7 ops/s 7.09 MB/s 36.80 us Batched WAL transaction commits, 32-byte IEEE CRC32 frame headers, and single-pass .snap checkpoint recovery.
4 KB CoW Volume Snapshot, Sync & Restore 120 577.98 ms 207.6 ops/s 6.49 MB/s 4,816.48 us Packed CAS Arena (chunks.pack + chunks.idx), Merkle delta sync planning, and verified streaming restore.
64 KB CoW Volume Snapshot & Restore (256 KB) 120 637.07 ms 188.4 ops/s 31.39 MB/s 5,308.90 us Workload-aligned 64 KB chunks (16x fewer index lookups) with constant-memory 2-pass streaming I/O.
Orchestrator Stack Reconcile & Rollback 100 7.13 ms 14,028.2 ops/s Control Plane 71.28 us Batched WAL persistence, multi-replica VIP reconciliation, and sub-millisecond metadata rollback.

3. Workload-Aligned CoW Volume Chunk Sizing

varc persistent volumes support power-of-2 multiples of 4 KB (4 KB, 8 KB, 16 KB, 32 KB, 64 KB, 128 KB, 256 KB, 512 KB, 1024 KB). Choosing the right --chunk-kb setting balances deduplication ratio against index size and sequential throughput:

Chunk Size (--chunk-kb) Ideal Workload Profile Deduplication vs. Bandwidth Trade-Off
4 KB Configuration directories, WebAssembly linear memory pages, small JSON/KV state files. Maximum fine-grained deduplication shared directly with .varc image chunks; higher index entry density.
8 KB - 16 KB Transactional relational databases (PostgreSQL 8 KB heap pages, SQLite/WAL journals). Aligns cleanly with database page writes so single-row updates dirty only one Merkle delta chunk.
64 KB - 256 KB Append-only analytics stores, vector indexes, Parquet segments, container log archives. 4.8x higher sequential snapshot/restore bandwidth (31.39 MB/s vs 6.49 MB/s) with 16x to 64x smaller chunks.idx maps.
512 KB - 1024 KB Large immutable model weights, firmware blobs, offline air-gapped datasets. Minimal metadata overhead and maximum sequential NVMe read/write throughput.

You can re-chunk an existing volume online using varc volume convert <vol_id> --dir <mount_path> --chunk-kb <new_kb> followed by varc system gc to reclaim superseded blocks.


4. Memory Footprint and Cluster Sizing Guidelines

  • Zero Idle Daemon Overhead: CLI commands (pack, verify, run, ps, up, rollback) run to completion and exit immediately with zero resident daemon memory when the Web Studio is not needed.
  • Control Plane Server (varc serve): Uses bounded in-memory maps plus a rotating 4,096-event active audit window (audit-archive.log holds historical segments on disk), keeping control-plane RAM usage under 25 MB for typical single-node and edge clusters.
  • Constant-Memory Volume Restoration & Compaction: Both varc volume restore and varc system gc stream chunks via positional file reads (O(chunk_size) buffer), preventing out-of-memory spikes even on multi-gigabyte chunks.pack arenas.

varc — Consolidated End-User, Administrator & Operations Handbook

varc — Rootless Single-File Container Runtime & Declarative Orchestrator


Part I: varc — Rootless Single-File Container Runtime & Declarative Orchestrator

varc (V Application Runtime & Containers) is a self-contained, zero-daemon, rootless container runtime, single-file image packager, zero-root virtual network overlay, Copy-on-Write (CoW) volume engine, and declarative multi-service orchestrator. It packages OS containers, OCI directory layouts, and WebAssembly 3.0 sandboxes into cryptographically signed .varc single-file bundles that verify and launch in milliseconds without requiring root privileges, background daemons, or external container tooling.

varc Developer Portal — Registered Single-File Container Bundles


Core Capabilities

Capability Operational Benefit
Single-File .varc Bundles Package application binaries, assets, OCI layouts, or Wasm modules into one immutable, Ed25519-signed .varc artifact with 4 KB SHA-256 Merkle chunk deduplication.
Rootless Multi-Backend Runtime Launch workloads across native Linux unprivileged namespaces (CLONE_NEWUSER, CLONE_NEWNS, CLONE_NEWPID, CLONE_NEWNET), transparent Windows-to-WSL2 bridges, or vvm WebAssembly 3.0 sandboxes.
Seccomp-BPF Monitor-to-Enforce Profile real workload system calls in monitor learning mode while blocking 41 high-risk kernel calls, then lock deterministic enforce BPF filters with one command or UI click.
Zero-Root 127.64.x.y VNet Mesh Assign collision-free 127.64.x.y loopback Virtual IPs and .varc / .vgate service DNS records without CAP_NET_ADMIN, TUN devices, or privileged CNI plugins.
Packed CAS CoW Volumes Capture, stream, and restore power-of-2 chunked (4 KB to 1024 KB) persistent volumes backed by an indexed Content-Addressable Storage arena (chunks.pack + chunks.idx).
Declarative Stacks & 1-Second Rollback Reconcile multi-service varc.conf stacks, Cron/Batch jobs, and horizontal autoscaling policies with atomic container + volume snapshot rollback.
4-Workspace Web Studio & REST API Operate clusters through an embedded Light/Dark Web Control Plane (/ui/auth, /ui/portal, /ui/delegated, /ui/admin) and OpenAPI 3.1 HTTP/1.1 server.

60-Second Quickstart

1. Generate a Signing Keypair & Package an Application

POWERSHELL
# Generate and pin a local Ed25519 bundle signing keypair
varc keygen --signer prod-release-ca --data-dir ./varc-data

# Package an application directory into a signed single-file .varc bundle
varc pack `
  --name hello-service `
  --version 1.0.0 `
  --dir ./examples/hello-service `
  --signer prod-release-ca `
  --tier network-service `
  --vip 127.64.2.10 `
  --out ./hello-service.varc `
  --data-dir ./varc-data

# Verify CRC32 framing, 4 KB Merkle root, and Ed25519 signature offline
varc verify ./hello-service.varc

2. Launch a Rootless Container & Inspect State

POWERSHELL
# Seal an encrypted runtime secret with AES-256-GCM
varc secret set db_password --value "s3cr3t-prod-credential" --data-dir ./varc-data

# Verify, materialize into CAS, and start the rootless container
varc run ./hello-service.varc `
  --id ctr-hello-01 `
  --name hello-api `
  --stack edge-api `
  --secret db_password `
  --data-dir ./varc-data

# List running containers, seccomp modes, and 127.64.x.y loopback VIPs
varc ps --data-dir ./varc-data

3. Start the 4-Workspace Web Studio Control Plane

POWERSHELL
# Start the HTTP/1.1 Control Plane and Web Studio on 127.0.0.1:8460
$env:VARC_API_TOKEN = "replace-with-strong-64-hex-operator-token"
varc serve --listen 127.0.0.1:8460 --data-dir ./varc-data

Open http://127.0.0.1:8460/ui/auth in any modern browser to authenticate and manage bundles, containers, seccomp policies, stacks, virtual networks, volumes, and hash-chained audit logs.


End-User Documentation Suite

Guide Audience & Scope
How-To Guide Task-oriented recipes for building .varc bundles, importing OCI directories, running rootless containers, locking seccomp profiles, configuring VNet VIPs, and managing CoW volumes.
User Guide Comprehensive walkthrough of workload lifecycles, Wasm 3.0 sandboxes, resource quotas, declarative stacks, Cron/Batch jobs, and all four Web Studio workspaces.
Administrator Guide Cluster bootstrap, API token & OIDC authentication, signer trust policies, AES-256-GCM secret rotation, multi-node scheduling, WAL compaction, CAS garbage collection, and audit verification.
Operations & Use Cases Production deployment blueprints (HA PostgreSQL, air-gapped edge delivery, trustnode.sh appliance fleets) and Day-2 incident response runbooks.
Configuration & CLI Reference Complete reference for all varc CLI subcommands, flags, environment variables, varc.conf declarative directives, and HTTP REST API endpoints.
Performance & Sizing Empirical 9-workload benchmark metrics, CoW volume chunk-sizing guidance, and node capacity planning.

Part II: How-To Guide

This guide provides step-by-step operational recipes for the most common packaging, runtime, security policy, networking, storage, and Web Studio workflows in varc.


1. Sign and Package a Directory into a .varc Bundle

Use varc keygen and varc pack to turn any self-contained service directory into an immutable, Ed25519-signed .varc bundle.

POWERSHELL
# 1. Create or load a named Ed25519 signing identity
varc keygen --signer release-eng-2026 --data-dir ./varc-data

# 2. Pack the directory into a signed single-file bundle
varc pack `
  --name checkout-api `
  --version 2.4.0 `
  --dir ./examples/hello-service `
  --entrypoint ./bin/hello-service `
  --seccomp monitor `
  --tier network-service `
  --net vnet `
  --vip 127.64.3.10 `
  --cpu 2000 `
  --memory 1024 `
  --signer release-eng-2026 `
  --out ./dist-bundles/checkout-api-2.4.0.varc `
  --data-dir ./varc-data

# 3. Inspect manifest metadata and verify cryptographic integrity
varc inspect ./dist-bundles/checkout-api-2.4.0.varc
varc verify ./dist-bundles/checkout-api-2.4.0.varc

2. Import an OCI Image Layout into .varc

Convert an unpacked OCI image directory (containing config.json and rootfs/) into a verified single-file .varc bundle with automatic path-traversal and tarbomb bounds checking:

POWERSHELL
varc import `
  --oci ./examples/oci-webapp `
  --name webapp-oci `
  --version 1.2.0 `
  --out ./dist-bundles/webapp-oci-1.2.0.varc `
  --data-dir ./varc-data

varc inspect ./dist-bundles/webapp-oci-1.2.0.varc --json

During import, varc validates archive relative paths, strips unsafe setuid/setgid mode bits (04000 / 02000), enforces a 1 GiB cumulative extraction ceiling, computes 4 KB SHA-256 Merkle chunk hashes, and signs the output bundle.


3. Launch Rootless Isolated Containers with Encrypted Secrets

Seal sensitive credentials in the node AES-256-GCM vault and mount them into a container's ephemeral secret directory without exposing plaintext in environment variables or image manifests:

POWERSHELL
# Store encrypted secrets in the node vault
varc secret set pg_dsn --value "postgres://app:s3cr3t@127.64.4.10:5432/orders" --data-dir ./varc-data
varc secret set jwt_hmac_key --value "9f8e7d6c5b4a39281716151413121110" --data-dir ./varc-data

# Run the verified bundle with strict signer verification and injected secrets
varc run ./dist-bundles/checkout-api-2.4.0.varc `
  --id ctr-checkout-01 `
  --name checkout-api `
  --stack commerce `
  --trust strict `
  --secret pg_dsn,jwt_hmac_key `
  --env LOG_LEVEL=info,PORT=8080 `
  --data-dir ./varc-data

# Check container status, runtime backend, and loopback VIP
varc ps --data-dir ./varc-data

When you stop and remove the container (varc stop ctr-checkout-01 followed by varc rm ctr-checkout-01), varc overwrites materialized secret files with zeros before unlinking the isolated rootfs.


4. Run an Unpacked Directory in an Ephemeral Rootless Sandbox

When testing a local binary or dynamically linked tool without building a .varc image first, use varc sandbox (alias varc jail):

POWERSHELL
# Scratch sandbox (isolated rootfs containing only the target directory and explicit library mounts)
varc sandbox ./examples/dynamic-sandbox `
  --id sbx-dyn-01 `
  --mode scratch `
  --tier strict-compute `
  --seccomp enforce `
  --net none `
  --cmd "./bin/app --self-test" `
  --data-dir ./varc-data

5. Profile System Calls in Monitor Mode and Lock an Enforce BPF Filter

Instead of hand-writing brittle seccomp JSON profiles, start a workload in monitor mode, feed observed system calls from staging integration tests, and lock the container into kernel enforce mode:

POWERSHELL
# Record observed staging syscalls against the network-service baseline and lock Enforce BPF
varc policy-learn `
  --container ctr-checkout-01 `
  --tier network-service `
  --syscalls "read,write,openat,close,socket,bind,listen,accept4,epoll_ctl,epoll_wait,futex,clock_gettime" `
  --data-dir ./varc-data

6. Configure Zero-Root Virtual Networks and .varc Service DNS

Deploy a multi-service stack manifest (varc.conf) to automatically allocate deterministic 127.64.x.y loopback Virtual IPs and .varc / .vgate service discovery domains:

POWERSHELL
# Deploy a multi-service stack
varc up -f ./examples/postgres-ha-stack/varc.conf --data-dir ./varc-data

# Inspect allocated 127.64.x.y VIPs, .varc/.vgate DNS records, and synthesized hosts entries
varc net --data-dir ./varc-data
varc net --hosts --data-dir ./varc-data

7. Manage Copy-on-Write Persistent Volumes and Snapshots

Capture deduplicated CoW snapshots before schema migrations, convert chunk granularity for large database/model files, and compute delta replication plans:

POWERSHELL
# Capture a 16 KB chunked CoW snapshot into the Packed CAS Arena
varc volume snapshot orders-db `
  --dir ./examples/hello-service `
  --mode merkle_chunk_stream `
  --chunk-kb 16 `
  --data-dir ./varc-data

# Re-chunk an existing volume to 64 KB blocks for sequential I/O workloads
varc volume convert orders-db --dir ./examples/hello-service --chunk-kb 64 --data-dir ./varc-data

# Inspect delta transfer requirements and restore to a target directory
varc volume sync-plan orders-db --data-dir ./varc-data
varc volume restore orders-db --target ./restored-orders-db --data-dir ./varc-data

8. Authenticate and Operate the Web Studio Control Plane

Start varc serve and open http://127.0.0.1:8460/ui/auth to establish an authenticated operator session:

varc Auth & Identity Workspace

  1. Paste the 256-bit node API token (from <data_dir>/keys/api.token or VARC_API_TOKEN) into Node API Token.
  2. Select your required operational scopes (varc:runtime:run, varc:seccomp:lock, varc:stack:deploy, varc:appliance:sign) and click Sign In & Establish Session.
  3. Switch to Developer Portal (/ui/portal) -> Rootless Containers & VIPs to inspect live container statuses, enforce/monitor seccomp modes, loopback VIPs, and .varc DNS records:

varc Active Rootless Containers & Loopback VIPs


Part III: User Guide

This guide explains varc core concepts, container and WebAssembly workload lifecycles, resource controls, declarative stack orchestration, and the 4-Workspace Web Studio interface.


1. Single-File .varc Bundles and Content-Addressable Storage

Traditional container workflows split images across dozens of compressed tar layers, registry manifests, and root-owned overlay filesystems. varc replaces layered tar archives with a deterministic single-file .varc container bundle:

  • Integrity & Provenance: Every bundle carries an IEEE CRC32 envelope checksum, per-file SHA-256 digests, a 4 KB chunked SHA-256 Merkle tree root, and an Ed25519 signature bound to a named signer identity.
  • Deduplicated CAS Materialization: When varc run or varc extract processes a bundle, verified chunks are stored once inside <data_dir>/cas/ and materialized into an isolated per-container root filesystem (<data_dir>/rootfs/<container_id>/) with sanitized permissions (0755 executables, 0644 regular files, zero setuid/setgid bits).
  • Trust Policies:
  • tofu (Trust On First Use, default for local development): Pins a newly encountered signer's Ed25519 public key on first verification and rejects any subsequent key mismatch for that signer ID.
  • strict (recommended for production): Requires the bundle's signer ID and public key to be pre-pinned via varc keygen or varc trust add.

2. Workload Kinds and Lifecycle Management

varc supports two first-class workload kinds under a unified CLI and REST API:

Workload Kind Target Platform Execution Backend Primary Use Case
os_container linux/amd64, linux/arm64 linux-rootless-ns on Linux; wsl2-linux-bridge on Windows Microservices, databases, network proxies, CLI batch workers, OCI imports.
wasm_vvm wasm32/wasm32 vvm-wasm3 (WebAssembly 3.0 / WASI 0.3) Sub-millisecond cold-start functions, user-defined database/analytics UDFs, multi-tenant plugins.

Container Lifecycle States

POWERSHELL
# Inspect container metadata, rootfs path, VIP, and resource quotas
varc inspect ctr-hello-01 --data-dir ./varc-data

# Read ring-buffered stdout/stderr logs
varc logs ctr-hello-01 --tail 100 --data-dir ./varc-data

# Execute a diagnostic command inside the container context
varc exec ctr-hello-01 ./bin/hello-service --health --data-dir ./varc-data

# Pause, resume, restart, stop, and cleanly remove a container
varc pause ctr-hello-01 --data-dir ./varc-data
varc resume ctr-hello-01 --data-dir ./varc-data
varc restart ctr-hello-01 --data-dir ./varc-data
varc stop ctr-hello-01 --data-dir ./varc-data
varc rm ctr-hello-01 --data-dir ./varc-data

WebAssembly 4 KB Copy-on-Write Checkpoints

For wasm_vvm containers, varc wasm-snap captures page-granular (4 KB) linear-memory snapshots directly into the node CAS arena so warm instances can be restored without re-running initialization:

POWERSHELL
varc wasm-snap ctr-wasm-udf-01 --pages 8 --data-dir ./varc-data

3. Resource Quotas and Isolation Boundaries

Every container enforces explicit CPU, memory, process-count, filesystem, and network boundaries:

  • CPU & Memory Quotas: Configured at pack time (--cpu <millicores>, --memory <mb>) or per-service in varc.conf (cpu_millicores, memory_max_mb, pids_max). On Linux cgroups v2 hosts, varc maps these directly to cpu.max, memory.max, and pids.max.
  • Zero Implicit Host Mounts: Unlike desktop container wrappers that bind-mount $HOME or host credential sockets by default, varc sets expose_host_home = false unconditionally and rejects mounts targeting sensitive host paths (host root, etc, proc, sys, dev, root, var/run, ~/.ssh).
  • Telemetry & Stats: Inspect live per-container CPU millicores, memory usage, and cluster capacity headroom with varc stats:
POWERSHELL
varc stats --data-dir ./varc-data
varc stats --json --data-dir ./varc-data

4. Declarative Stacks, Cron/Batch Jobs, and Autoscaling

A single varc.conf file declares services, persistent volumes, scheduled Cron or parallel Batch jobs, and horizontal autoscaling rules.

POWERSHELL
# Reconcile a declarative stack
varc up -f ./examples/ecommerce-stack/varc.conf --data-dir ./varc-data

# Scale a specific service horizontally
varc scale commerce/checkout --replicas 4 --data-dir ./varc-data

# List and manually trigger scheduled Cron/Batch jobs
varc jobs --data-dir ./varc-data
varc job-run nightly-settlement --data-dir ./varc-data

# Evaluate horizontal autoscale policy against observed metrics
varc autoscale commerce/checkout --cpu 82 --memory 65 --rps 420 --data-dir ./varc-data

# Instant 1-second rollback to previous healthy stack & volume snapshot revision
varc rollback commerce --data-dir ./varc-data

5. Navigating the 4-Workspace Web Studio

varc serve hosts a zero-dependency Web Studio divided into four role-focused workspaces:

Workspace 1: Auth & Identity (/ui/auth)

Authenticate with your 256-bit node API token or OIDC provider, select granular session scopes using removable multi-select chips, inspect keyless Ed25519 bundle signing settings, and verify active rootless UID/GID namespace mappings.

Workspace 2: Developer & Application Portal (/ui/portal)

Browse registered .varc container and Wasm bundles with their 4 KB Merkle roots, transition containers from monitor learning mode into enforce BPF mode, and inspect active containers alongside their 127.64.x.y loopback VIPs:

varc Developer Portal — Registered Bundles

Workspace 3: Stack, Rollback & Jobs Operations (/ui/delegated)

Monitor WAL-backed multi-service stack revisions, trigger 1-Click Rollback across containers and CoW volume snapshots, trigger Cron/Batch jobs on demand, and review horizontal autoscaling policies:

varc Stack & Jobs Operations Workspace

Workspace 4: Fleet, VNet & Security Administration (/ui/admin)

Deploy turnkey trustnode.sh appliance suites (security, core, data, ai), inspect the zero-root 127.64.x.y VNet DNS mesh, monitor persistent volume replication states, and audit the SHA-256 hash-chained event ledger in either Light Mode or Dark Mode (Dark / Light toggle in the top header).


Part IV: Administrator Guide

This guide covers node bootstrap, authentication hardening, cryptographic signer governance, admission policy enforcement, multi-node cluster management, storage compaction, and tamper-evident audit verification for varc operators.


1. Node Data Directory Layout and Bootstrap Security

When varc initializes a node (--data-dir <path>, default data/varc), it creates a structured, self-contained state hierarchy:

TEXT
<data_dir>/
  commit.log              # 32-byte VPRV IEEE CRC32 Write-Ahead Log
  state.snap              # Atomic TSV checkpoint snapshot
  audit-archive.log       # Rotated SHA-256 hash-chained RFC 5424 audit segments
  keys/
    master.kek            # 256-bit Node Key-Encryption Key (0600 permissions)
    api.token             # 256-bit Bootstrap Control Plane API Token (0600 permissions)
    <signer>.ed25519.enc  # AES-256-GCM KEK-sealed Ed25519 private signing keys
  cas/
    chunks.pack           # Contiguous Packed Content-Addressable Storage arena
    chunks.idx            # SHA-256 -> (offset, length) chunk index
  rootfs/
    <container_id>/       # Per-container isolated root filesystem & zeroizable secrets
  seccomp/
    <container_id>.seccomp.conf  # Locked Monitor -> Enforce syscall profiles
  volumes/
    snaps/<snap_id>.snap.tsv     # Per-revision CoW volume snapshot manifests

2. Control Plane Authentication and Session Governance

All mutating and state-reading /api/v1/* endpoints require authentication via either:

  1. Bearer API Token: Set VARC_API_TOKEN in the service environment (minimum 32 hex/ASCII characters recommended) or read the auto-generated 256-bit token at <data_dir>/keys/api.token.
  2. HttpOnly Session Cookie: Established via POST /api/v1/auth/session (used by /ui/auth) with mandatory CSRF header enforcement (X-Varc-Requested-With: 1) and SameSite=Strict.
POWERSHELL
# Start Control Plane bound strictly to loopback or a private management interface
$env:VARC_API_TOKEN = "d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3"
varc serve --listen 127.0.0.1:8460 --data-dir ./data

3. Admission Policy Enforcement and Trusted Signers

Pinning and Revoking Ed25519 Bundle Signers

In production clusters, enforce --trust strict so only bundles signed by explicitly pinned release keys can execute:

POWERSHELL
# Pin an offline CI/CD release signing public key
varc trust add `
  --signer prod-release-ca `
  --pubkey 9261829d380df711264bb9feef978c77a04cb4177899a56e30673f9cdb5bd81e `
  --data-dir ./data

# Audit currently trusted signers and trust sources
varc trust list --data-dir ./data

# Immediately revoke a retired or compromised signing identity
varc trust rm prod-release-ca --data-dir ./data

Baseline Seccomp-BPF Tiers

Every OS container is assigned a baseline syscall tier combined with an unconditional 41-syscall kernel deny list:

Tier Baseline Syscalls Intended Workloads
strict-compute 24 Pure compute workers, parsers, batch transformers (net=none).
crypto-appliance 31 Key management, signing authorities, token issuers (getrandom, mlock).
network-service 47 HTTP/gRPC APIs, reverse proxies, connection poolers (socket, epoll_wait, accept4).
filesystem-worker 63 Databases, CoW volume replicators, search indexers (fsync, fdatasync, renameat2).

4. Zero-Root VNet Mesh and Multi-Node Cluster Scheduling

varc assigns each node a /24 slice inside 127.64.<subnet>.0/24 and resolves .varc and .vgate service domains without requiring root privileges or kernel bridge modules:

varc Fleet Admin — Zero-Root 127.64.x.y Loopback VIP & DNS Mesh

Managing Cluster Nodes

Register worker nodes with CPU, memory, subnet, and topology zone labels for anti-affinity bin-packing scheduling:

POWERSHELL
# Register two availability-zone worker nodes
varc node join node-east-01 --addr 10.20.1.11:8460 --subnet 11 --cpu 16000 --memory 32768 --labels zone=us-east-a,tier=compute --data-dir ./data
varc node join node-east-02 --addr 10.20.1.12:8460 --subnet 12 --cpu 16000 --memory 32768 --labels zone=us-east-b,tier=compute --data-dir ./data

# Inspect node capacity and health
varc node list --data-dir ./data

# Cordoning/draining a node prior to OS patching
varc node drain node-east-01 --data-dir ./data
varc node rm node-east-01 --data-dir ./data

5. Storage Compaction, CAS Garbage Collection, and Audit Verification

Run routine Day-2 storage maintenance and cryptographic audit verification via varc system:

POWERSHELL
# 1. Compact commit.log into an atomic state.snap checkpoint and truncate WAL
varc system checkpoint --data-dir ./data

# 2. Run streaming Tri-Root Mark-and-Sweep CAS Garbage Collection
#    (preserves chunks referenced by active images, retained stack revisions, and volume snapshots)
varc system gc --data-dir ./data

# 3. Cryptographically verify the SHA-256 hash-chained RFC 5424 audit ledger
varc system audit-verify --data-dir ./data

# 4. Stream recent security and lifecycle audit events
varc events --tail 50 --data-dir ./data

varc Fleet Admin Dark Mode — SHA-256 Hash-Chained Audit Ledger & SOAR Quarantine


6. Upgrades, Backup, and Disaster Recovery

  1. Pre-Upgrade Checkpoint: Run varc system checkpoint and capture fresh volume snapshots (varc volume snapshot <vol_id> --dir <mount_path> --mode merkle_chunk_stream).
  2. Atomic Binary Upgrade: Because varc is a single static-style executable with zero background daemon lock-in, replace the varc binary in place and verify varc version.
  3. Post-Upgrade Verification: Run varc system audit-verify and varc health <stack_name> to confirm WAL state recovery, intact audit hash chains, and healthy service VIPs.

Part V: Operations & Use Cases

This guide presents production deployment architectures, end-to-end configuration manifests, REST API automation workflows, and incident response runbooks for varc.


Use Case 1: Stateful HA PostgreSQL + Wasm Analytics Stack with 1-Second Rollback

Organizations running transactional PostgreSQL clusters alongside low-latency analytics functions often struggle to coordinate schema upgrades, connection pooler updates, and data volume snapshots. With varc, a single declarative varc.conf manages OS containers, vvm WebAssembly 3.0 UDF workers, CoW persistent volumes, and health-gated rollback.

Declarative Stack Manifest (postgres-ha.varc.conf)

INI
stack_name = postgres-ha-stack
version = 16.4.0

[volume.pg-heap]
mount_path = ./volumes/pgdata
quota_mb = 16384
chunk_size_kb = 64
replication_mode = wal_delta_sync

[service.pg-primary]
image = postgres-varc:16.4.0
replicas = 1
vip = 127.64.4.10
port = 5432
seccomp_mode = enforce
seccomp_tier = filesystem-worker
volume = pg-heap:./volumes/pgdata
cpu_millicores = 4000
memory_max_mb = 8192

[service.pg-bouncer]
image = pgbouncer-varc:1.22.0
replicas = 2
vip = 127.64.4.11
port = 6432
seccomp_mode = enforce
seccomp_tier = network-service
depends_on = pg-primary

[service.wasm-analytics-udf]
image = udf-rollup-wasm:1.0.0
workload_kind = wasm_vvm
replicas = 2
vip = 127.64.4.12
port = 8090
seccomp_mode = enforce
seccomp_tier = strict-compute

[job.nightly-wal-verify]
image = pg-verify-job:1.0.0
kind = cron
schedule = "0 2 * * *"
concurrency = forbid

Deployment, Health Probing, and Automated Rollback

POWERSHELL
# Apply the stack (automatically snapshots CoW volumes prior to revision rollout)
varc up -f ./postgres-ha.varc.conf --data-dir ./data

# Probe TCP health across stack VIPs and auto-rollback if any replica fails readiness
varc health postgres-ha-stack --probe-tcp --auto-rollback --data-dir ./data

# Or trigger explicit rollback to a specific historical revision
varc rollback postgres-ha-stack --revision 1 --data-dir ./data

Use Case 2: Air-Gapped & Edge Single-File Appliance Delivery

Remote industrial gateways, defense enclaves, and retail edge nodes frequently lack outbound container registry connectivity and prohibit root daemons. varc enables deterministic single-file delivery over optical diodes or USB media:

  1. Build Zone (Connected CI):
POWERSHELL
   varc keygen --signer edge-release-2026 --data-dir ./ci-state
   varc pack --name edge-telemetry --version 3.1.0 --dir ./build/rootfs `
     --seccomp enforce --tier network-service --signer edge-release-2026 `
     --out ./edge-telemetry-3.1.0.varc --data-dir ./ci-state
  1. Air-Gapped Edge Host (Zero Network Access):
POWERSHELL
   # Pin the public key once during host provisioning
   varc trust add --signer edge-release-2026 --pubkey <64-hex-ed25519-pubkey> --data-dir ./data

   # Offline cryptographic verification (CRC32 + 4 KB Merkle + Ed25519)
   varc verify ./edge-telemetry-3.1.0.varc

   # Launch unprivileged with strict trust enforcement
   varc run ./edge-telemetry-3.1.0.varc --trust strict --seccomp enforce --data-dir ./data

Use Case 3: Turnkey trustnode.sh Security & Infrastructure Fleet

varc includes built-in appliance packaging and one-command suite orchestration for the 11 trustnode.sh infrastructure services (vca, vwarden, vsight, vgate, vvm, vprevail, vstore, vft, vkbm, vllm, vsite):

POWERSHELL
# Package an individual appliance with deterministic VIP and seccomp tier defaults
varc appliance --project vgate --out ./bundles/vgate.varc --data-dir ./data

# Deploy the security suite (vca, vwarden, vsight on 127.64.0.11..13)
varc trustnode-up --suite security --data-dir ./data

# Or deploy via the authenticated Control Plane REST API
curl -sS -X POST http://127.0.0.1:8460/api/v1/stacks/apply \
  -H "Authorization: Bearer $VARC_API_TOKEN" \
  -H "X-Varc-Requested-With: 1" \
  -H "Content-Type: application/json" \
  -d '{"suites":"security,core"}'

Use Case 4: Private AI & Knowledge Retrieval Appliance (ai-rag-stack)

Teams deploying internal retrieval-augmented generation (RAG) pipelines need strict isolation between public ingress, vector/knowledge indexing, and compute-heavy model inference—without relying on external cloud registries or privileged container daemons. The examples/ai-rag-appliance/varc.conf blueprint pairs vgate-ingress, vkbm-index, and vllm-inference over the 127.64.x.y loopback mesh:

  • Large-Chunk Model Weights (512 KB): The model-weights volume uses 512 KB CoW chunks (quota_mb = 32768, merkle_chunk_stream) so multi-gigabyte model files deduplicate and stream with minimal index overhead.
  • Tiered Seccomp Isolation: vgate-ingress runs under network-service, vkbm-index under filesystem-worker, and vllm-inference under strict-compute.
  • Scheduled Index Compaction & RPS Autoscaling: A 6-hour Cron job (30 */6 * * *) compacts knowledge indexes while vllm-inference scales between 1 and 6 replicas based on CPU (75%) and request rate (50 RPS per replica).
POWERSHELL
# Deploy the AI & Knowledge Retrieval stack
varc up -f ./examples/ai-rag-appliance/varc.conf --data-dir ./data

# Verify VNet VIPs (.varc / .vgate DNS) and volume chunk geometry
varc net --hosts --data-dir ./data
varc volumes --data-dir ./data

# Evaluate inference autoscaling under load (e.g., 82% CPU, 240 RPS)
varc autoscale ai-rag-stack/vllm-inference --cpu 82 --memory 68 --rps 240 --data-dir ./data

Use Case 5: E-Commerce Microservices with Secrets, Batch Jobs & Safe Rollback

Multi-service transactional applications must coordinate encrypted API credentials, stateful order storage, background batch reindexing, and instant rollback when a release degrades readiness checks. The examples/ecommerce-stack/varc.conf manifest demonstrates this full lifecycle:

  1. Seal Runtime Credentials First:
POWERSHELL
   varc secret set db_password --value "prod-orders-db-pass" --data-dir ./data
   varc secret set stripe_webhook_secret --value "whsec_live_example" --data-dir ./data
  1. Deploy the Stack (edge-proxy, checkout-api, orders-worker):
POWERSHELL
   # Applies 3 services, 16 KB-chunk orders-data volume, nightly cron, and 4-way batch reindex
   varc up -f ./examples/ecommerce-stack/varc.conf --data-dir ./data

   # Inspect running containers and health probe status across 127.64.2.10..12
   varc ps --data-dir ./data
   varc health ecommerce-stack --probe-tcp --data-dir ./data
  1. Roll Back Atomically on Regression:
POWERSHELL
   # Revert containers, secrets bindings, and orders-data volume snapshot in one command
   varc rollback ecommerce-stack --data-dir ./data

Use Case 6: Ephemeral Scratch Sandboxing for Untrusted Binaries & Plugins

When you need to run a third-party CLI tool, vendor diagnostic binary, or CI build plugin without packing a .varc image—and without exposing host /usr, /lib, or home directories—use varc sandbox in --mode scratch. Using examples/dynamic-sandbox/:

BASH
# Run an unpacked app with explicitly staged vendor libraries and zero network access
varc sandbox --id sbx-vendor-audit --mode scratch \
  --dir ./examples/dynamic-sandbox/app \
  --lib-dir ./examples/dynamic-sandbox/vendor-libs \
  --lib-path ./lib:./lib64:./vendor/lib \
  --seccomp monitor --tier strict-compute \
  --net none \
  -- ./bin/worker.sh

# Inspect sandbox telemetry and exit status as JSON
varc sandbox --id sbx-vendor-audit --mode scratch \
  --dir ./examples/dynamic-sandbox/app \
  --lib-dir ./examples/dynamic-sandbox/vendor-libs \
  --json -- ./bin/worker.sh

Once the sandbox run finishes, any temporary rootfs state is discarded, leaving the host filesystem untouched.


Use Case 7: Hybrid Native + WebAssembly 3.0 (vvm) Edge Workers

For latency-sensitive request filters, webhook transformers, or untrusted tenant plugins, you can package WebAssembly 3.0 / WASI 0.3 modules as first-class .varc bundles and run them alongside native OS containers:

POWERSHELL
# 1. Package a Wasm 3.0 module into a signed .varc bundle
varc pack `
  --name webhook-filter `
  --version 1.0.0 `
  --kind wasm_vvm `
  --dir ./build/wasm-filter `
  --entrypoint ./filter.wasm `
  --tier strict-compute `
  --seccomp enforce `
  --vip 127.64.5.20 `
  --signer prod-release-ca `
  --out ./bundles/webhook-filter-1.0.0.varc `
  --data-dir ./data

# 2. Verify and launch inside the vvm CoW sandbox
varc verify ./bundles/webhook-filter-1.0.0.varc
varc run ./bundles/webhook-filter-1.0.0.varc --id ctr-wasm-filter-01 --data-dir ./data

Because vvm isolates linear memory with 4 KB Copy-on-Write pages, multiple tenant invocations can be snapshotted and restored in microseconds without spinning up separate OS namespaces per request.


Use Case 8: Live & Air-Gapped Host Migration for OS Containers (varc migrate & .varc-mig)

When draining a host for kernel maintenance or rebalancing stateful services across nodes, varc supports both live HTTP/1.1 node-to-node migration and offline/air-gapped .varc-mig staged bundle migration. Both paths enforce 3-pass pre-copy volume Merkle delta sync, hybrid AES-256-GCM secret re-wrapping, .learn.tsv seccomp session continuity, and monotonic migration_epoch split-brain fencing.

Form A: One-Command Live HTTP/1.1 Migration (varc migrate <id> --to <node>)

When both nodes are reachable over the Control Plane API, run a single command (or POST /api/v1/migrations/live) to execute the entire flow—pre-condition checks, pre-drain hook, 3-pass pre-copy CAS delta sync, HTTP/1.1 transfer, vnet 500–2000 ms hold-buffer cutover, and source fencing:

POWERSHELL
# One-command live migration with a pre-drain hook
varc migrate ctr-checkout-01 `
  --to node-b `
  --target-addr 127.0.0.1:8470 `
  --pre-drain-hook "http://127.64.2.11:8080/drain" `
  --secrets pg_dsn,jwt_hmac_key `
  --volume-dir ./volumes/orders `
  --data-dir ./data

Or trigger the same one-shot live migration over HTTP:

BASH
curl -sS -X POST http://127.0.0.1:8460/api/v1/migrations/live \
  -H "Authorization: Bearer $VARC_API_TOKEN" \
  -H "X-Varc-Requested-With: 1" \
  -H "Content-Type: application/json" \
  -d '{"container_id":"ctr-checkout-01","target_node":"node-b","target_addr":"127.0.0.1:8470","pre_drain_hook":"signal:SIGUSR1","secrets":"pg_dsn,jwt_hmac_key"}'

Form B: Air-Gapped .varc-mig Staged Migration

For disconnected enclaves or shared-storage handoffs without direct node-to-node HTTP connectivity:

POWERSHELL
# 1. On Source Host: export signed .varc-mig bundle with re-wrapped secrets
varc migrate export ctr-checkout-01 `
  --to node-b `
  --out ./ctr-checkout-01.varc-mig `
  --volume-dir ./volumes/orders `
  --secrets pg_dsn,jwt_hmac_key `
  --target-pubkey <target-ed25519-pub-hex> `
  --data-dir ./data

# 2. On Target Host: verify CRC32 + Ed25519 + per-chunk SHA-256 and commit at epoch+1
varc migrate import ./ctr-checkout-01.varc-mig `
  --trusted-pubkey <source-ed25519-pub-hex> `
  --data-dir ./data

# 3. On Source Host: fence old instance and zeroize local secrets
varc migrate fence ctr-checkout-01 --migration <mig-id> --epoch 2 --data-dir ./data

Use Case 9: Live Cross-OS & Cross-Architecture wasm_vvm Migration (.varc-ckpt)

Unlike native OS binaries (os_container), which require matching CPU architectures and compatible Linux/WSL2 hosts, wasm_vvm sandboxes execute portable WebAssembly 3.0 bytecode. When varc migrates a wasm_vvm workload (for example, moving an edge worker from a linux/x86_64 node to a macos/arm64 node), it suspends execution at a cooperative safe point and emits a signed .varc-ckpt (VARCCKPT) checkpoint envelope:

  1. Pre-Copy 4 KB Dirty Pages: Only 4 KB linear-memory pages modified since the baseline snapshot are included, verified per page via SHA-256.
  2. Deterministic Execution State: Globals, indirect-call table slots, call frames, remaining fuel quota, instruction pointer, and virtualized WASI 0.3 file descriptors (with seek cursors) are serialized alongside the memory delta.
  3. Sub-Second Resume: The target vvm runtime verifies the Ed25519 signature and aggregate Merkle root, patches the 4 KB dirty pages, and resumes execution from the exact safe point.

Migration Best Practices, Pre/Post Conditions & Gotchas

Pre-Conditions (Checked Before Migration Starts)

  • Source Container State: The container must be running or paused, and its migration_state must be none (not already migrating_out or fenced).
  • Target Node Readiness & Headroom: In live cluster mode, the target node must be ready (not draining, cordoned, or offline) with enough available CPU millicores and memory MB.
  • OS & Architecture Compatibility: os_container workloads require matching CPU architecture and compatible OS (linux <-> wsl2). wasm_vvm workloads can migrate across any OS and CPU architecture.
  • Trust & Secret Keying: For air-gapped .varc-mig transfers, pin the source signer's Ed25519 public key (--trusted-pubkey) on the target and pass --target-pubkey during export so secrets are wrapped specifically for the target node.

Post-Conditions (Guaranteed After Successful Migration)

  • Target Active at epoch + 1: The target container is running with migration_state = none and migration_epoch = epoch + 1.
  • Source Fenced & Zeroized: The source container is stopped, migration_state = fenced at epoch + 1, and its materialized secrets are zeroized. Any partitioned node reconnecting with a stale epoch self-fences automatically.
  • Audit & Continuity Preserved: seccomp monitor-mode .learn.tsv sessions, CAS delta chunks, and SHA-256 hash-chained audit events are intact on both nodes.

Best Practices & Common Gotchas

  • Use a Pre-Drain Hook (--pre-drain-hook) for Stateful Apps: Point --pre-drain-hook to a loopback endpoint (http://127.64.x.y:port/drain) or signal (signal:SIGUSR1) so databases and workers flush write buffers before the final delta pass. Non-loopback HTTP hooks are blocked by the built-in SSRF guard.
  • Watch for Write-Heavy Churn (--force-pause): varc caps pre-copy at 3 passes. If a workload mutates volume chunks faster than they can sync, varc aborts safely without touching the running container. Use --force-pause during a maintenance window if you want varc to pause the workload and force the final delta.
  • Open TCP Connections on os_container: varc stays 100% rootless and zero-dependency (no CRIU), so vnet's 500–2000 ms hold buffer buffers new connections during cutover while existing connections drain. Place vgate ingress in front of services if clients need automatic retry on in-flight HTTP requests.
  • Use vprevail Quorum Fencing for Multi-Node HA: For 3+ node clusters, configure VprevailQuorumFenceProvider so lease acquisition requires a strict majority (N/2 + 1), preventing split-brain even during asymmetric network partitions.

Production Day-2 Incident Runbooks

Runbook A: Immediate SOAR Container Quarantine

When an anomaly detector (such as vsight) flags suspicious egress or unexpected behavior in a running workload, quarantine the container without destroying forensic rootfs or memory state:

BASH
curl -sS -X POST http://127.0.0.1:8460/api/v1/containers/quarantine \
  -H "Authorization: Bearer $VARC_API_TOKEN" \
  -H "X-Varc-Requested-With: 1" \
  -H "Content-Type: application/json" \
  -d '{"container_id":"ctr-commerce-checkout-1"}'

Quarantine atomically pauses the container execution state, revokes its 127.64.x.y virtual network peer routes, and appends a signed container.quarantine event to the SHA-256 hash-chained audit log.

Runbook B: Live Traffic Spike & Horizontal Autoscale Reconciliation

BASH
# Query real-time CPU, memory, and autoscale telemetry
curl -sS http://127.0.0.1:8460/api/v1/stats \
  -H "Authorization: Bearer $VARC_API_TOKEN"

# Trigger policy-based horizontal scale evaluation via CLI
varc autoscale commerce/checkout --cpu 88 --memory 70 --rps 650 --data-dir ./data

Runbook C: Corrupted Disk Tail Recovery & Audit Verification

If a host suffers an unclean power loss mid-deployment:

  1. Run varc system audit-verify --data-dir ./data. During store open, varc validates every 32-byte VPRV IEEE CRC32 WAL frame and automatically truncates any incomplete torn tail frame cleanly to the last committed transaction boundary.
  2. Run varc system checkpoint --data-dir ./data to persist a fresh state.snap image.
  3. Run varc ps --data-dir ./data and varc health <stack_name> --probe-tcp to confirm service availability.

Part VI: Configuration & CLI Reference

This reference documents all varc command-line subcommands, flags, environment variables, varc.conf declarative stack directives, and HTTP/1.1 Control Plane REST API endpoints.


1. Global Node Flags and Environment Variables

All stateful CLI subcommands accept the following node flags:

Flag Default Description
--data-dir <path> data/varc Path to the node state directory containing WAL, CAS arena, keys, rootfs, and volume snapshots.
--listen <host:port> 127.0.0.1:8460 TCP bind address for varc serve and node discovery metadata.
--json / -j false Emit structured JSON output on supported inspection and listing commands.

Environment Variables

Variable Purpose
VARC_API_TOKEN Overrides the on-disk <data_dir>/keys/api.token Bearer token used by varc serve for HTTP API and Web Studio authentication.
VARC_DATA_DIR Optional default override for --data-dir when not explicitly passed on the command line.
VARC_LISTEN_ADDR Optional default override for --listen (127.0.0.1:8460).

2. Image, Signing & Appliance Subcommands

Subcommand Syntax & Key Options Description
pack varc pack --name <name> --version <ver> --dir <src_dir> [--out <file.varc>] [--kind os_container|wasm_vvm] [--entrypoint <path>] [--seccomp monitor|enforce] [--tier <tier>] [--net isolated|vnet|none] [--vip <127.64.x.y>] [--cpu <m>] [--memory <mb>] [--signer <id>] Package a directory into a signed .varc single-file container or Wasm bundle.
import varc import --oci <oci_dir> --name <name> --version <ver> [--out <file.varc>] Import an unpacked OCI layout (config.json + rootfs/) into a signed .varc bundle.
appliance varc appliance --project <vca|vwarden|vsight|vgate|vvm|...> [--dir <src_dir>] [--out <file.varc>] Package a trustnode.sh appliance with preset VIP and seccomp tier defaults.
inspect varc inspect <file.varc | container_id | image_id> [--json] Display bundle manifest/signature details or registered container/image state.
verify varc verify <file.varc> Verify 64-byte header framing, IEEE CRC32, 4 KB Merkle tree root, and Ed25519 signature.
extract varc extract <file.varc> [--cas <dir>] [--rootfs <dir>] Materialize verified .varc files into a CAS directory and isolated rootfs.
images varc images [--json] List registered .varc bundles, workload kinds, signers, sizes, and Merkle roots.
rmi varc rmi <image_id_or_name> [--force] Remove a registered image record from the node catalog.
keygen varc keygen [--signer <id>] Generate or load an AES-256-GCM KEK-sealed Ed25519 signing keypair and pin its public key.
trust varc trust <list | add --signer <id> --pubkey <hex> | rm <id>> List, pin, or revoke trusted Ed25519 bundle signers.

3. Rootless Runtime, Sandbox & Policy Subcommands

Subcommand Syntax & Key Options Description
run varc run <file.varc> [--id <cid>] [--name <name>] [--stack <stack>] [--trust tofu|strict] [--seccomp monitor|enforce] [--net isolated|vnet|none] [--vip <ip>] [--secret <s1,s2>] [--env <K=V,...>] [--exec] Verify, extract into CAS/rootfs, compile BPF policy, and launch a rootless container.
sandbox / jail varc sandbox <dir_or_bin> [--id <id>] [--mode scratch|ro-system] [--tier <tier>] [--seccomp monitor|enforce] [--net none|isolated] [--lib-dir <path>] [--cmd "<args>"] Execute an unpacked binary or directory inside an ephemeral rootless namespace sandbox.
ps varc ps [--json] List registered containers, statuses, seccomp modes, loopback VIPs, and runtime backends.
stop / pause / resume / restart varc <stop|pause|resume|restart> <container_id> Transition container execution state and update durable WAL state.
rm varc rm <container_id> [--force] Remove a stopped container, zeroize materialized secrets, and delete its isolated rootfs.
logs varc logs <container_id> [--tail <lines>] Read ring-buffered container standard output and error streams.
exec varc exec <container_id> [--live] <command...> Execute a diagnostic command inside a running container context.
wasm-snap varc wasm-snap <container_id> [--pages <1..64>] Capture a 4 KB CoW linear-memory checkpoint for a wasm_vvm sandbox.
policy-learn varc policy-learn --container <cid> [--tier <tier>] --syscalls "<s1,s2,...>" Record legitimate syscalls in Monitor mode, block high-risk calls, and lock an Enforce BPF profile.

4. Orchestrator, Volume, Cluster & System Subcommands

Subcommand Syntax & Key Options Description
up varc up -f <path/to/varc.conf> Reconcile a declarative stack manifest, volumes, DNS records, jobs, and autoscale policies.
down varc down <stack_name> Stop all containers belonging to a stack and zeroize mounted secrets.
scale varc scale <stack>/<service> --replicas <n> Horizontally scale service replicas within a deployed stack.
rollback varc rollback <stack_name> [--revision <n>] Roll back stack containers and CoW persistent volume snapshots to a prior healthy revision.
health varc health <stack_name> [--probe-tcp] [--auto-rollback] Probe service readiness (with SSRF guard) and optionally auto-rollback unhealthy revisions.
stacks varc stacks [--json] List deployed stack revisions and active container memberships.
jobs / job-run varc jobs [--json] / varc job-run <job_id> List registered Cron/Batch jobs or trigger immediate job execution.
volumes / volume varc volume <list | snapshot <id> --dir <d> [--mode <m>] [--chunk-kb <k>] | convert <id> --dir <d> --chunk-kb <k> | restore <id> --target <d> | sync-plan <id>> Manage CoW persistent volumes, Packed CAS chunk granularity, delta plans, and restores.
secret varc secret <list | set <name> --value <v|-> | get <name> | rm <name>> Manage NIST SP 800-38D AES-256-GCM encrypted runtime secrets.
net / dns varc net [--hosts] [--json] Display allocated 127.64.x.y loopback VIPs, .varc/.vgate DNS records, or etc/hosts blocks.
stats varc stats [--json] Display container CPU/memory telemetry, cluster capacity, and autoscale rules.
autoscale varc autoscale <stack>/<service> --cpu <pct> --memory <pct> --rps <n> Evaluate horizontal autoscaling thresholds and adjust replica counts.
node varc node <list | join <id> --addr <h:p> --subnet <n> --cpu <m> --memory <mb> [--labels <k=v>] | drain <id> | rm <id>> Manage multi-node cluster membership, VIP subnet slices, and scheduling state.
migrate varc migrate <<cid> --to <node> [--target-addr <h:p>] [--pre-drain-hook <hook>] [--force-pause] | export <cid> --to <node> --out <file.varc-mig> [--volume-dir <d>] [--secrets <s1,s2>] [--target-pubkey <hex>] [--force-pause] | import <file.varc-mig> [--trusted-pubkey <hex>] | fence <cid> --migration <id> --epoch <n>> Execute one-command live migration or export, import, and epoch-fence .varc-mig bundles.
trustnode-up varc trustnode-up [--suite security|core|data|ai|all] Deploy turnkey trustnode.sh infrastructure appliance suites.
system varc system <checkpoint | gc | audit-verify | events> Compact WAL snapshots, run Tri-Root CAS garbage collection, or verify SHA-256 audit chains.
events varc events [--tail <n>] [--json] Tail SHA-256 hash-chained RFC 5424 audit records.
serve varc serve [--listen <addr>] [--max-requests <n>] [--dry-run] Start the HTTP/1.1 Control Plane REST API and 4-Workspace Web Studio server.
openapi varc openapi Print the complete OpenAPI 3.1.0 JSON specification to stdout.
discovery varc discovery Emit JSON node capability and endpoint discovery metadata.
bench varc bench [--markdown] [--dir <temp_dir>] Run the 9-workload empirical performance benchmark suite.

5. Declarative varc.conf Configuration Schema

varc.conf uses a clean, deterministic INI/key-value section syntax with zero external parser dependencies:

INI
# Global stack metadata
stack_name = commerce
version = 2.1.0

# Persistent Copy-on-Write volume declaration
[volume.orders-data]
mount_path = ./volumes/orders
quota_mb = 4096
chunk_size_kb = 16
replication_mode = merkle_chunk_stream

# Service declaration (OS container or wasm_vvm)
[service.checkout]
image = checkout-api:2.1.0
workload_kind = os_container
replicas = 2
vip = 127.64.2.20
port = 8080
seccomp_mode = enforce
seccomp_tier = network-service
network_mode = vnet
cpu_millicores = 1000
memory_max_mb = 512
volume = orders-data:./volumes/orders
secrets = db_password,stripe_webhook_secret
depends_on = orders-db

# Scheduled Cron or Parallel Batch job
[job.nightly-ledger-sync]
image = ledger-worker:2.1.0
kind = cron
schedule = "30 1 * * *"
concurrency = forbid

# Policy-driven horizontal autoscaler
[autoscale.checkout]
min_replicas = 2
max_replicas = 8
target_cpu_percent = 75
target_memory_percent = 80
target_rps_per_replica = 250
cooldown_seconds = 60

6. HTTP/1.1 Control Plane REST API Endpoints

All /api/v1/* routes (except /healthz, /readyz, and /api/v1/auth/session) require Authorization: Bearer <token> (or an active varc_session cookie) and X-Varc-Requested-With: 1 on POST mutations.

Method Path Purpose
GET /healthz, /readyz Unauthenticated liveness and readiness probes (200 OK).
GET /openapi.json Full OpenAPI 3.1.0 Control Plane schema.
GET /ui/auth, /ui/portal, /ui/delegated, /ui/admin 4-Workspace Web Studio HTML5 Control Plane views.
POST /api/v1/auth/session Validate API token and issue HttpOnly; SameSite=Strict operator session cookie.
POST /api/v1/auth/logout Invalidate active operator session cookie.
GET /api/v1/images List registered .varc bundles and 4 KB Merkle roots.
GET /api/v1/containers List containers, statuses, seccomp modes, loopback VIPs, and DNS domains.
GET /api/v1/stacks List deployed stack revisions and container memberships.
GET /api/v1/jobs List registered Cron and Batch jobs with execution counters.
GET /api/v1/network List zero-root 127.64.x.y VIP allocations and .varc/.vgate DNS records.
GET /api/v1/volumes List persistent volumes, chunk sizes, replication modes, and latest snapshot IDs.
GET /api/v1/stats Retrieve container CPU/memory telemetry, cluster node headroom, and autoscale rules.
GET /api/v1/audit Retrieve SHA-256 hash-chained RFC 5424 security and lifecycle audit events.
POST /api/v1/seccomp/lock Lock a container's learned monitor syscall profile into enforce mode ({"container_id":"..."}).
POST /api/v1/stacks/apply Deploy one or more trustnode.sh appliance suites ({"suites":"security,core"}).
POST /api/v1/stacks/rollback Roll back a stack and its CoW volumes ({"stack_name":"...","target_revision":"0"}).
POST /api/v1/jobs/trigger Trigger immediate execution of a registered Cron/Batch job ({"job_id":"..."}).
POST /api/v1/containers/quarantine Atomically pause a container, isolate its VIP, and log a SOAR quarantine audit event ({"container_id":"..."}).
GET /api/v1/migrations List durable cross-host migration records, phases, and monotonic migration_epoch values.
POST /api/v1/migrations/export Run pre-flight checks, 3-pass pre-copy CAS delta sync, and export a signed .varc-mig payload.
POST /api/v1/migrations/import Verify .varc-mig, apply CAS deltas and wrapped secrets, and commit target container at epoch+1.
POST /api/v1/migrations/fence Fence a migrated source container at epoch+1 and zeroize its materialized secrets.
POST /api/v1/migrations/live Execute one-command live migration (pre-conditions, pre-drain hook, 3-pass pre-copy, HTTP stream, and source fence).

Part VII: Performance & Sizing Guide

varc includes a built-in, deterministic 9-workload benchmark harness (varc bench) that measures cryptographic secret sealing, 4 KB SHA-256 Merkle tree reduction, single-file .varc bundle signing and verification, seccomp-bpf compilation, VPRV Write-Ahead Log replay, Packed CAS Copy-on-Write volume streaming, and declarative stack rollback.


1. Running the Built-In Benchmark Suite

Run the empirical benchmark suite on any host to measure local CPU, memory, and storage performance:

POWERSHELL
# Console summary table
varc bench

# GitHub-flavored Markdown report for release validation or capacity baselining
varc bench --markdown

# Benchmark against a specific storage mount (e.g., NVMe production volume)
varc bench --dir ./data/bench-tmp --markdown

2. Empirical 9-Workload Benchmark Baseline

The table below records measured production-build (-prod) throughput, bandwidth, and average per-operation latency across all nine core runtime and control-plane hot paths:

Workload Operations Elapsed (ms) Throughput (ops/sec) Bandwidth (MB/s) Avg Latency (us) Architectural Design Characteristic
AES-256-GCM Seal & Unseal (4 KB) 500 85.22 ms 5,867.0 ops/s 22.92 MB/s 170.44 us Precomputed expanded AES-256 key schedule, unique 96-bit IVs, stack-allocated 16-byte cipher blocks, and branchless GF(2^128) authentication.
.varc 4 KB Merkle Tree (256 KB / 64 Chunks) 200 359.67 ms 556.1 ops/s 139.02 MB/s 1,798.34 us Contiguous flat digest arena with in-place binary tree reduction and zero intermediate slice cloning.
.varc Bundle Pack & Ed25519 Sign (64 KB) 100 458.09 ms 218.3 ops/s 13.83 MB/s 4,580.92 us Single-pass envelope serialization, IEEE CRC32 framing, 4 KB SHA-256 Merkle root, and Ed25519 signing.
.varc Bundle Unpack & Full Verify (64 KB) 200 434.84 ms 459.9 ops/s 29.14 MB/s 2,174.18 us 6-stage admission check: magic bytes, bounds guard, CRC32, per-file SHA-256, Merkle root, and constant-time Ed25519 verify.
Seccomp-BPF Learn & Filter Compile 2,000 56.99 ms 35,094.9 ops/s 49.00 MB/s 28.49 us Zero-allocation syscall ABI number dispatch, O(1) 41-syscall high-risk deny check, and pre-sized BPF filter emission.
VPRV 32B CRC32 WAL Append, Snap & Replay 1,000 36.80 ms 27,170.7 ops/s 7.09 MB/s 36.80 us Batched WAL transaction commits, 32-byte IEEE CRC32 frame headers, and single-pass .snap checkpoint recovery.
4 KB CoW Volume Snapshot, Sync & Restore 120 577.98 ms 207.6 ops/s 6.49 MB/s 4,816.48 us Packed CAS Arena (chunks.pack + chunks.idx), Merkle delta sync planning, and verified streaming restore.
64 KB CoW Volume Snapshot & Restore (256 KB) 120 637.07 ms 188.4 ops/s 31.39 MB/s 5,308.90 us Workload-aligned 64 KB chunks (16x fewer index lookups) with constant-memory 2-pass streaming I/O.
Orchestrator Stack Reconcile & Rollback 100 7.13 ms 14,028.2 ops/s Control Plane 71.28 us Batched WAL persistence, multi-replica VIP reconciliation, and sub-millisecond metadata rollback.

3. Workload-Aligned CoW Volume Chunk Sizing

varc persistent volumes support power-of-2 multiples of 4 KB (4 KB, 8 KB, 16 KB, 32 KB, 64 KB, 128 KB, 256 KB, 512 KB, 1024 KB). Choosing the right --chunk-kb setting balances deduplication ratio against index size and sequential throughput:

Chunk Size (--chunk-kb) Ideal Workload Profile Deduplication vs. Bandwidth Trade-Off
4 KB Configuration directories, WebAssembly linear memory pages, small JSON/KV state files. Maximum fine-grained deduplication shared directly with .varc image chunks; higher index entry density.
8 KB - 16 KB Transactional relational databases (PostgreSQL 8 KB heap pages, SQLite/WAL journals). Aligns cleanly with database page writes so single-row updates dirty only one Merkle delta chunk.
64 KB - 256 KB Append-only analytics stores, vector indexes, Parquet segments, container log archives. 4.8x higher sequential snapshot/restore bandwidth (31.39 MB/s vs 6.49 MB/s) with 16x to 64x smaller chunks.idx maps.
512 KB - 1024 KB Large immutable model weights, firmware blobs, offline air-gapped datasets. Minimal metadata overhead and maximum sequential NVMe read/write throughput.

You can re-chunk an existing volume online using varc volume convert <vol_id> --dir <mount_path> --chunk-kb <new_kb> followed by varc system gc to reclaim superseded blocks.


4. Memory Footprint and Cluster Sizing Guidelines

  • Zero Idle Daemon Overhead: CLI commands (pack, verify, run, ps, up, rollback) run to completion and exit immediately with zero resident daemon memory when the Web Studio is not needed.
  • Control Plane Server (varc serve): Uses bounded in-memory maps plus a rotating 4,096-event active audit window (audit-archive.log holds historical segments on disk), keeping control-plane RAM usage under 25 MB for typical single-node and edge clusters.
  • Constant-Memory Volume Restoration & Compaction: Both varc volume restore and varc system gc stream chunks via positional file reads (O(chunk_size) buffer), preventing out-of-memory spikes even on multi-gigabyte chunks.pack arenas.