VATN — Virtual Application Transaction Node

A high-performance, plugin-native JVM runtime for building distributed applications and agentic systems.

VATN gives you the developer ergonomics of Node.js — one-liner server start, drop-in plugins, built-in pub/sub — but runs on the JVM with Java 25 virtual threads, delivering throughput comparable to Go or Rust while shipping a full production stack out of the box: HTTP, WebSocket, DAG workflows, distributed tracing, secrets, cryptographic identity, and LAN federation.

┌─────────────────────────────────────────────────────────────────┐
│  Your Plugin          implements VNodePlugin                    │
│  onInitialize(ctx) → ctx.register("/api", new MyService());     │
│                                                                 │
│  VNodeRunner.create(8080).addPlugin(new MyPlugin()).start();    │
└─────────────────────────────────────────────────────────────────┘

Why VATN?

	Node.js / Express	Spring Boot	VATN
Startup time	~300 ms	~4–8 s	~200 ms (JVM) / ~10 ms (native)
HTTP throughput (TechEmpower-style)	~78 k req/s	~243 k req/s	~310 k req/s
Concurrency model	Event loop (async/await)	Thread pool or reactive	Virtual threads — blocking style, zero threads wasted
Plugin system	NPM packages	Spring Beans / auto-config	`VNodePlugin` SPI — JAR drop-in, hot-swap, trust-level enforcement
DAG / workflow engine	Bull, Agenda (third-party)	Spring Batch (heavy)	Built-in `VDagEngine` — Airflow-inspired, SQLite-backed, crash-safe
Work queues	Bull/BullMQ + Redis	RabbitMQ / SQS clients	`VQueueService` — named queues, claim/ack, DLQ, atomic enqueue; no broker
Durable pub/sub	Kafka / Redis Streams	Spring Cloud Stream	`VTopicService` — per-consumer offsets, replay, seek; SQLite-backed
Advisory locks	Redlock (Redis)	`@Lock` + DB row	`VResourceLockService` — TTL-protected, RAII `VLock`, crash-safe
Rate limiting	express-rate-limit / Nginx	Spring `@RateLimiter`	`VRateLimiter` — inbound routes + outbound upstream quotas; per-second or windowed
Outbound HTTP	axios / node-fetch	RestTemplate / WebClient	`VHttpClient` — resilient: retry/backoff, ETag/TTL cache, per-host circuit breaker
Periodic scheduler	node-cron / Agenda	`@Scheduled`	`VScheduler` — cron or fixed-interval, skip-on-overlap, virtual-thread dispatch
Blob / content store	multer + S3 SDK	Spring Content	`VBlobStore` — CAS (sha256), streaming, range reads, pin/evict; S3 backend via plugin
Cross-node RPC	HTTP calls + discovery	Spring Cloud OpenFeign	`VRpcService` — typed request/response over OIPC/VMessaging, correlation + timeout
Data sync / replication	custom + CRDTs	Hazelcast / Infinispan	`VReplicationService` — change-feed, per-peer watermarks, LWW/custom conflict resolution, partial replication
Full-text search	elasticsearch client	Spring Data + Lucene	`vatn-plugin-fts` — SQLite FTS5, BM25, snippets, no infrastructure
Secrets	dotenv / Vault SDK	Spring Vault	`VSecretService` — AES-256-GCM, filesystem-backed, vault-ready SPI
Node identity	None	None	Ed25519 key pair per node, sign/verify data
Federation	None	None	UDP LAN discovery (v1); full lattice mesh (v2)
GraalVM native image	No	Optional	First-class — `vatn_node_start()` C ABI
Language interop	N-API (C)	JNI	OIPC v2.12 — language-agnostic binary protocol over UDS/TCP

On queues and topics without a broker: The work-queue and durable-topic design was inspired by honker — the idea that if SQLite is already your primary store, the message queue and event stream should live in the same file. This eliminates the dual-write problem between business tables and a separate broker, and removes an entire infrastructure component from your stack.

Architecture

 ┌──────────────────────────────────────────────────────────────────────┐
 │                          vatn-api  (SPI)                             │
 │  VNodePlugin · VNodeContext · VHttpService · VMessaging · VDagEngine │
 │  VGuardService · VSecretService · VNodeIdentity · VDiscovery · ...   │
 └───────────────────────────┬──────────────────────────────────────────┘
                             │  implemented by
 ┌───────────────────────────▼──────────────────────────────────────────┐
 │                       vatn-core  (runtime)                           │
 │                                                                      │
 │   VNodeRunner ──── Helidon 4 SE HTTP ──── VHttpService adapters      │
 │        │                                                             │
 │        ├── VRegistry (PF4J plugin loader, Ed25519 verification)      │
 │        ├── VDagEngineImpl  (SQLite-backed, crash-safe replay)        │
 │        ├── OipcMessagingTransport  (UDS / TCP, OIPC v2.12)           │
 │        ├── VNodeIdentityImpl  (Ed25519 keypair, ~/.vatn/.identity)   │
 │        ├── VSecretServiceImpl  (AES-256-GCM, ~/.vatn/secrets/)       │
 │        ├── VUdpDiscovery  (UDP multicast LAN announcements)          │
 │        └── VNativeBridge  (@CEntryPoint C ABI for GraalVM)           │
 └──────────────┬───────────────────────────────────────────────────────┘
                │  loaded into
 ┌──────────────▼───────────────────────────────────────────────────────┐
 │             Your plugins  /  vatn-plugin-*                           │
 │   your own VNodePlugin impls  ·  vatn-plugins ecosystem              │
 └──────────────────────────────────────────────────────────────────────┘

 ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌────────────┐
 │  vatn-cli    │  │  vatn-bench  │  │  vatn-test   │  │ vatn-spec  │
 │  vatn run    │  │  JMH / wrk   │  │  harness     │  │ OIPC spec  │
 │  vatn init   │  │  benchmarks  │  │              │  │            │
 │  vatn test   │  └──────────────┘  └──────────────┘  └────────────┘
 └──────────────┘

Installation

The fastest way to get VATN running — one command installs the CLI, GraalVM (optional), and your chosen plugins.

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/RainerXE/vatn/main/install.sh -o install.sh && bash install.sh

Windows (PowerShell — run as Administrator)

Set-ExecutionPolicy Bypass -Scope Process -Force
irm https://raw.githubusercontent.com/RainerXE/vatn/main/install.ps1 | iex

What the installer does

Detects your current Java installation (Java 21+ required)
Offers to install GraalVM via SDKMAN / winget (Oracle GraalVM or CE — your choice)
Asks where to install (default ~/.vatn)
Presents a plugin selection menu — recommended defaults pre-selected, all available
Downloads vatn-cli.jar and selected plugin JARs from the latest GitHub Release
Creates a vatn launcher on your PATH with an auto-discovered plugin classpath
Writes a default vatn.conf configuration file
Optionally clones the source repos into a development folder so you can build your own plugins or contribute to the runtime

Installed layout

~/.vatn/
├── bin/vatn            ← the vatn command (added to PATH)
├── lib/vatn-cli.jar    ← runtime fat-JAR
├── plugins/            ← drop plugin JARs here; all auto-loaded at startup
├── config/
│   └── vatn.conf       ← node configuration
└── logs/

After installation

source ~/.zshrc           # (or ~/.bashrc; open a new terminal on Windows)

vatn --version            # VATN Runtime 1.0.0
vatn init my-project      # scaffold a new plugin project
cd my-project
vatn run                  # starts node on :8080

Open http://localhost:8080/vatn/admin for the admin dashboard (set VATN_ADMIN_TOKEN first).

Non-interactive / CI install

Override prompts with environment variables:

VATN_INSTALL_DIR=~/.vatn \
VATN_JAVA=graal \
VATN_PLUGINS=cors,auth,swagger,admin,postgres \
  bash <(curl -fsSL https://raw.githubusercontent.com/RainerXE/vatn/main/install.sh)

Variable	Values	Default
`VATN_INSTALL_DIR`	any path	`~/.vatn`
`VATN_JAVA`	`graal` / `graalce` / `skip`	interactive
`VATN_PLUGINS`	comma list, `recommended`, `all`	interactive

Plugins

The full plugin catalog — auth, postgres, redis, openai, slack, WASM, TerminalPhone, and more — lives in vatn-plugins →.

Building your first plugin

A step-by-step walkthrough with code, Node.js analogies, DAG workflows, security, and deployment is in vatn-plugins — Quick Start →.

Build from Source

If the installer offered to clone the source repos, your repos are already in your development folder.
Otherwise, clone them manually:

git clone https://github.com/RainerXE/vatn.git
git clone https://github.com/RainerXE/vatn-plugins.git   # optional — drop-in plugins
git clone https://github.com/RainerXE/vatn-demo.git      # optional — examples & tutorials

Prerequisites

Java 25+ — GraalVM 25 recommended (sdk install java 25.0.2-graal via SDKMAN)
Maven 3.9+

Build the runtime

cd vatn
mvn clean install -DskipTests
# → vatn-api/target/vatn-api-1.0-SNAPSHOT.jar   (SPI — depend on this in your plugins)
# → vatn-core/target/vatn-core-1.0-SNAPSHOT.jar  (runtime — never depend on this directly)
# → vatn-cli/target/vatn-cli-1.0-SNAPSHOT.jar    (fat JAR — use as the vatn launcher)

Build plugins

cd vatn-plugins
mvn clean install -DskipTests
# → vatn-plugin-*/target/vatn-plugin-*.jar

Deploy your build to the local installation

cp vatn/vatn-cli/target/vatn-cli-*.jar ~/.vatn/lib/vatn-cli.jar
cp vatn-plugins/vatn-plugin-*/target/vatn-plugin-*.jar ~/.vatn/plugins/

Build modes

All three modes require GraalVM 25 (install once via SDKMAN):

sdk install java 25.0.2-graal
sdk use java 25.0.2-graal

JVM + Project Leyden AOT cache (~116 ms cold start)

mvn package verify -Pleyden -pl vatn-cli -am -DskipTests
java -XX:AOTCache=vatn-cli/target/vatn.aot \
     -jar vatn-cli/target/vatn-cli-1.0-SNAPSHOT.jar --help

GraalVM native image (~24 ms cold start, no JVM required)

mvn clean package -Pnative -pl vatn-cli -am -DskipTests
./vatn-cli/target/vatn --version   # VATN Runtime 1.0.0

Mode	Cold start	JVM required	Distribution
JVM plain	~144 ms	Yes (Java 25)	JAR (22 MB)
JVM + Leyden AOT	~116 ms	Yes (same JVM)	JAR + cache (37 MB)
Native image	~24 ms	No	Binary (113 MB)

Plugin model in native mode: Dynamic JAR loading is disabled in native image. Plugins ship compiled-in (Path A) or as separate OIPC processes (Path B). See docs/dev-guide.md § Native image.

Run the hello-world example

cd vatn/examples/01-hello-world
mvn package -DskipTests
java -jar target/01-hello-world-1.0-SNAPSHOT.jar
# → http://localhost:8080/hello

Process Sandbox

VATN provides a layered sandboxing stack that any application plugin can use. The entire stack sits in vatn-core; your plugin only sees vatn-api interfaces.

Architecture

Plugin code
    │  ctx.getService(VSandboxProvider.class).exec("odin check .", 30)
    ▼
VSandboxProvider (vatn-api SPI)
    │  default impl: LocalSandbox (your app, implements the SPI)
    │  calls VGuardService.evaluateToolCall() first
    │  reads VatnSecurity.CURRENT_TRUST_LEVEL (ScopedValue)
    ▼
VProcessService.execute(cmd, env, dir, trustLevel)   (vatn-api SPI)
    │  impl: LocalProcessService (vatn-core)
    │
    ├─► ShellEnvPolicy.applyTo(pb.environment())     env isolation
    │       reads [sandbox.shell_env] from .vatn/vatn.toml
    │       default: inherit=core + exclude secret patterns
    │
    └─► OsSandboxWrapper.wrapCommand(cmd, trustLevel) OS sandboxing
            macOS  → sandbox-exec -p "(deny file-write*)(deny network*)"
            Linux  → bwrap --ro-bind / / --unshare-all / --share-net
            FULL   → no wrapper (command runs as-is)
    ▼
VSubprocessAuditService.record(entry)                audit
    registered by VNodeRunner; queryable via getAll() / getForSession()

Trust Levels

`VTrustLevel`	macOS sandbox	Linux sandbox	Use case
`FULL`	none	none	Trusted internal tools
`RESTRICTED`	deny file-write	ro-bind + share-net	Semi-trusted tools (network allowed)
`SANDBOXED`	deny file-write + deny network	ro-bind + unshare-all	Untrusted or user-supplied commands

VatnSecurity.CURRENT_TRUST_LEVEL is a Java ScopedValue — set it before dispatching to a tool and it propagates automatically to VProcessService.

Environment isolation (`ShellEnvPolicy`)

Configure in .vatn/vatn.toml:

[sandbox.shell_env]
inherit  = "core"                          # all | core | none
exclude  = ["AWS_*", "*_KEY", "*_TOKEN", "ANTHROPIC_*", "OPENAI_*"]
set      = { CI = "true" }                 # always present, overrides existing

`inherit`	Behaviour
`core`	Keep only safe vars: `PATH`, `HOME`, `JAVA_HOME`, `LANG`, `TMPDIR`, `CI`, …
`all`	Keep full parent env, then apply `exclude` patterns
`none`	Empty env — only keys from `set` are present

If .vatn/vatn.toml is absent or has no [sandbox.shell_env] section, the safe default is used: inherit = "core" with standard secret patterns excluded.

Using `VSandboxProvider` in your plugin

public class MyPlugin implements VNodePlugin {
    @Override
    public void onInitialize(VNodeContext ctx) {

        // Execute a command with the default (FULL) trust level
        VSandboxProvider sandbox = ctx.getService(VSandboxProvider.class).orElseThrow();
        String output = sandbox.exec("odin check .", 30);

        // Execute with restricted trust (propagated to LocalProcessService)
        ScopedValue.where(VatnSecurity.CURRENT_TRUST_LEVEL, VTrustLevel.SANDBOXED)
            .run(() -> {
                String result = sandbox.exec("user-supplied-command", 10);
                // process result
            });
    }
}

Querying the audit log

Every call that reaches VSandboxProvider (and any plugin that writes to VSubprocessAuditService directly) is logged in memory:

VSubprocessAuditService audit = ctx.getService(VSubprocessAuditService.class).orElseThrow();

// All entries
List<VSubprocessAuditEntry> all = audit.getAll();

// Per-session
List<VSubprocessAuditEntry> forSession = audit.getForSession(sessionId);

// JSON — for a REST handler
res.sendJson(audit.toJsonArray());

Each VSubprocessAuditEntry carries: sessionId, command, exitCode, durationMs, timestamp.

The default implementation is in-memory only (resets on node restart). To persist across restarts, register your own database-backed implementation before VNodeRunner.start():

VNodeRunner runner = VNodeRunner.create(8080);
runner.registerService(VSubprocessAuditService.class, new MyDbAuditService(dataSource));
runner.addPlugin(new MyPlugin());
runner.start();

Providing a custom `VSandboxProvider`

The default VSandboxProvider is whatever your application registers. If you don't register one, ctx.getService(VSandboxProvider.class) returns empty. Register your implementation in onInitialize:

ctx.registerService(VSandboxProvider.class, new MyCustomSandbox(ctx));

Project Modules

`vatn-api` — The SPI (Start here)

Zero external dependencies. Every interface your plugin ever touches lives here. You compile your plugin against vatn-api only; the runtime (vatn-core) is provided by the node.

Key surfaces:

Interface	Purpose
`VNodePlugin`	Implement this; `onInitialize(ctx)` wires your services
`VNodeContext`	Entry point to every service: `ctx.getMessaging()`, `ctx.getService(VDagEngine.class)`, …
`VHttpService` / `VHttpRoutes`	Declare REST endpoints and WebSocket handlers
`VHttpFilter` / `VFilterChain`	Per-request middleware chain — auth, CORS, security headers, tracing
`VMessaging`	In-process ephemeral pub/sub; same API as cross-node OIPC in v2
`VDagEngine` / `VDagRegistry`	Define and trigger DAG workflows
`VQueueService` / `VNamedQueue`	Named work queues — claim/ack, priority, DLQ, delayed jobs, atomic enqueue
`VTopicService` / `VTopic`	Durable pub/sub topics — per-consumer offsets, replay, seek, pause/resume
`VResourceLockService` / `VLock`	Advisory TTL locks — `tryAcquire` / `acquire` returning RAII `VLock` handles
`VRateLimiter`	Token-bucket rate limiter — inbound routes and outbound upstreams; per-second or arbitrary-window quotas (`configure(key, 1000, Duration.ofDays(1))`); blocking `acquire` + `millisUntilAvailable` for outbound callers
`VHttpClient`	Outbound HTTP SPI — `RetryPolicy` (exponential backoff, jitter, `Retry-After`), `CachePolicy` (ETag/TTL), `CircuitBreakerPolicy` (per-host); response carries headers for conditional revalidation
`VScheduler`	Lightweight periodic scheduler — 5-field cron (`cron(name, expr, task)`) or fixed interval (`every(name, Duration, task)`), skip-on-overlap, decoupled from the DAG engine
`VBlobStore`	Content/blob-store SPI — content-addressing (`putContent` → `"sha256:<hex>"`), streaming, byte-range reads (`openRange(key, offset, length)`), pin/evict local cache; runtime default is a local CAS under `~/.vatn/blobs`; `vatn-plugin-s3` provides an S3 backend
`VRpcService`	Application-level cross-node RPC over `VMessaging` — typed request/response with correlation IDs, timeout, and error propagation; today in-process, federated under Lattice v2
`VReplicationService`	Index sync / replication primitive — change-feed, per-peer watermarks, pluggable `VConflictResolver` (default: last-writer-wins), `VReplicationFilter` for partial replication
`VGuardService`	Intercept input, output, and tool calls for PII / SSRF filtering
`VSecretService`	Store and retrieve encrypted secrets
`VNodeIdentity`	Sign and verify data with the node's Ed25519 key
`VDiscovery` / `VNameResolver`	LAN peer discovery (v1) and name resolution
`VTracingService`	Distributed tracing (noop by default; OTLP via `VATN_OTLP_ENDPOINT`)
`VSandboxProvider`	Execute shell commands inside the node's security sandbox — guard-checked, OS-isolated, audit-logged
`VSubprocessAuditService` / `VSubprocessAuditEntry`	Append-only log of every subprocess execution: sessionId, command, exitCode, durationMs, timestamp
`VWasmRuntime` / `VWasmModule`	Load and execute `.wasm` modules — interpreter or native-compile backends
`workflow.*`	Full DAG model: `VDag`, `VDagTask`, `VOperator`, `VXCom`, `VPool`, `VEventLog`, `VDagScheduler`
`replication.*`	Replication model: `VChange`, `VConflictResolver`, `VReplicationFilter`, `VReplicationConfig`, `VReplicatedSet`
`security.*`	`VFirewall`, `VFlowPolicy`, `VPolicyInterjector`, `VTrustLevel`, `VSecretService`

`vatn-core` — The Runtime Engine

The Helidon 4 SE–powered implementation of every vatn-api interface. You never depend on this in your plugin — it is the runtime that runs your plugin.

Notable internals:

VNodeRunner — one-liner bootstrap; wires HTTP router, plugin lifecycle, DAG engine, messaging services, OIPC transport, and all platform services
VDagEngineImpl — Airflow-style task graph execution on virtual threads; SQLite persistence; crash-safe replay via VEventLog
VQueueServiceImpl — named work queues backed by vatn_named_queue_jobs; visibility-timeout sweeper on a background virtual thread; supports DLQ forwarding and atomic enqueue on a caller-supplied connection
VTopicServiceImpl — durable pub/sub backed by vatn_topic_events + per-consumer vatn_topic_offsets; offset auto-saved every 1000 events or 1 second; consumers resume from their saved position on restart
VResourceLockServiceImpl — SQLite-backed TTL advisory locks; tryAcquire / acquire return VLock RAII handles that release on close()
VTokenBucketRateLimiter — lazy-refill token bucket with nanosecond precision; supports per-second limits and arbitrary-window quotas (e.g. 1 000 permits/day); acquire blocks a virtual thread; millisUntilAvailable returns a backoff hint
VResilientHttpClient — retry-with-backoff decorator over JavaVHttpClientImpl; per-key retry policy (exponential + jitter + Retry-After), ETag/TTL response cache (LRU, max 1 024 entries), and per-host circuit breaker (CLOSED / HALF_OPEN / OPEN); registered as the default VHttpClient; rate-limit-bound to respect outbound upstream quotas automatically
VSchedulerImpl — virtual-thread-backed periodic scheduler; 5-field cron via CronEvaluator (reusable class shared with the DAG scheduler); fixed-interval alternative; skip-on-overlap guarantee; registered as VScheduler
LocalBlobStore — content-addressed local blob cache under ~/.vatn/blobs; SHA-256 keyed, deduplicating, byte-range reads, LRU eviction of unpinned blobs; registered as VBlobStore (overridden by vatn-plugin-s3 when that plugin is loaded)
VRpcServiceImpl — request/response RPC over VMessaging; length-prefixed binary framing with correlation IDs; per-call timeout watchdog on a virtual thread; server-side dispatch on virtual threads; registered as VRpcService
VReplicationServiceImpl — change-feed pull/push over VRpcService; per-peer watermarks in vatn_repl_watermark; Lamport-clock versioning; pluggable VConflictResolver; VReplicationFilter for partial replication (per-peer key-space sharding)
OipcMessagingTransport — OIPC v2.12 binary protocol over Unix Domain Sockets (TCP fallback); full HELLO handshake; async virtual-thread accept loop
VNativeBridge — GraalVM @CEntryPoint C ABI; exposes vatn_node_start, vatn_node_stop, vatn_call, vatn_get_diagnostics
VRegistry — PF4J-based plugin loader with Ed25519 JAR signature verification; trust-level assignment (SANDBOXED → RESTRICTED → FULL)
LocalProcessService — VProcessService impl that applies ShellEnvPolicy (env isolation) and OsSandboxWrapper (OS-native sandboxing) before every subprocess spawn
OsSandboxWrapper — wraps commands with OS-native sandbox tools based on VTrustLevel: sandbox-exec on macOS, bwrap on Linux
VSubprocessAuditServiceImpl — in-memory audit log; registered automatically by VNodeRunner; replace with a DB-backed impl if you need persistence across restarts

`vatn-cli` — Developer Toolbelt

vatn run   [--port N] [--plugins <path>]   Start a VATN node
vatn init  [--lang java|python] <name>     Scaffold a new plugin project
vatn test  [--path <plugin-dir>]           Run the test harness against a plugin
vatn info                                  Print node info and loaded services
vatn registry                              Manage remote plugin registries
vatn oipc-benchmark                        Run the OIPC wire-level latency benchmark

Built with Picocli; produces a single fat JAR. A GraalVM native binary is the intended distribution format.

`vatn-bench` — Benchmarks

JMH micro-benchmarks and external load-test scripts:

Benchmark	What it measures
`WorkflowDagBench`	DAG trigger latency, fan-out throughput, XCom pipeline, crash-resume overhead
`JsonBench`	Jackson parse/stringify throughput, VJson query
`HttpServerBench`	In-process HTTP handler throughput
`bench/http/run.sh`	External wrk load against a live VATN node
`bench/workflow/run.sh`	DAG throughput vs Windmill / Prefect / Airflow
`bench/report/generate.sh`	Aggregate all results into a dated Markdown report

`examples/` — Working Examples

Eleven runnable projects, each a self-contained Maven module:

#	Example	Concepts covered
01	Hello World	Minimal plugin, single GET endpoint
02	REST API (Task Manager)	CRUD, path params, JSON, SQLite persistence
03	WebSocket Chat	Real-time bi-directional messaging, broadcast
04	DAG ETL Pipeline	Workflow engine, operators, XCom, retry policy
05	Real-time Dashboard	SSE, pub/sub, live metric streaming to browser
06	Scheduled Report	Cron DAG, sensors, automated scheduled workflows
07	Chat App	Full-stack HTML UI + WebSocket, rooms, history
08	Chaos Suite	OIPC watchdog, process restart, memory limits
09	Polyglot FFI	Java + C + Odin via Java 25 Panama (FFM)
10	Python Plugin	Raw Python OIPC socket plugin
11	Custom Guard	PII redaction, keyword filtering, SSRF blocking

`vatn-test` — Plugin Test Harness

Standalone harness for black-box testing a VATN plugin. Boots a minimal node, loads the plugin under test, runs assertions against its HTTP surface and messaging output. Suitable for CI without mocking the runtime.

`vatn-spec` — Protocol Specifications

OIPC-212-alignment.md — Full VATN alignment document for the OIPC v2.12 "Relentless" wire protocol: 18-byte V3 binary header, HELLO handshake, VOipcMessageType opcode table, shutdown RELAXED/STRICT, trust-level enforcement, policy resolution

`vatn-verify` — Protocol Verification Tools

Standalone tools for verifying OIPC wire compliance: byte-level frame inspection, handshake validation, and message-type conformance checks. Used by CI and plugin authors to validate custom OIPC implementations.

`docs/` — Documentation

Document	Contents
dev-guide.md	Start here. Beginner's guide — install, build, first plugin, HTTP, DAG, security. Analogies to Node.js throughout.
oipc-protocol.md	OIPC v2.12 binary wire spec — header layout, opcodes, HELLO handshake, lifecycle channels
vatn-architecture.md	VATN/Applications boundary, repo layout, dev workflow

OIPC Protocol

VATN nodes communicate over OIPC (Octet IPC) v2.12 "Relentless" — a lightweight binary/JSON protocol over Unix Domain Sockets (TCP fallback). The Java VNodePlugin SPI abstracts OIPC entirely; you only need it directly to write plugins in Python, Rust, or C.

Wire format: 18-byte V3 header (0x4F magic, version, opcode, flags, length) + payload. Full spec: docs/oipc-protocol.md.

Federation (v1 now, v2 roadmap)

Every VATN node runs VUdpDiscovery at startup: it joins the 224.0.0.251:7719 multicast group and announces itself every 5 seconds. VDiscovery and VNameResolver are live services — nodes on the same LAN find each other automatically.

v2 (VATN Lattice) upgrades this to production-grade federation: cryptographic node bonding, encrypted cross-node channels, federated DAG execution with nodeAffinity, distributed VMessaging across nodes, and a gossip-based mesh. Your plugin code does not change — VNodeContext is the same interface.

Performance

Measured on Apple M5, wrk -t8 -c256 -d30s:

Scenario	Throughput
VATN `/ping` (plain text)	~310,000 req/s
VATN `/json` (small JSON object)	~280,000 req/s
Spring Boot 3	~243,000 req/s
Node.js / Express	~78,000 req/s
Python / FastAPI	~25,000 req/s

DAG engine latency (JMH, warm JVM):

Scenario	Avg latency
Single-task DAG trigger	~0.8 ms
10-task serial chain	~9 ms
10-task fan-out (parallel)	~2 ms
Windmill (Python, 40 tasks)	~2,400 ms
Apache Airflow (40 tasks)	~56,000 ms

Documentation Index


Beginner's guide	docs/dev-guide.md
Examples	examples/README.md
OIPC wire protocol	docs/oipc-protocol.md
Architecture	docs/vatn-architecture.md
API source	`vatn-api/src/main/java/dev/vatn/api/`
Benchmarks	`vatn-bench/bench/`
Plugin catalog	vatn-plugins →

Ecosystem

Repository	Purpose
vatn-plugins	Drop-in plugins — auth, postgres, redis, openai, WASM, Tor/voice, and more
vatn-demo	Ports of well-known systems (Bull.js, Celery, Express, …) to VATN with migration tutorials

License

VATN is released under the MIT License.

MIT License

Copyright (c) 2026 VATN Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Third-Party Dependencies

VATN bundles or depends on the following open-source libraries. All are permissively licensed and compatible with the MIT License.

Runtime dependencies

Library	Version	License	Used in
Eclipse Helidon SE	4.4.1	Apache 2.0	HTTP, WebSocket, SSE, tracing (`vatn-core`)
Jackson Databind	2.16.1	Apache 2.0	JSON serialisation (`vatn-core`)
PF4J	3.9.0	Apache 2.0	Plugin loader and lifecycle (`vatn-core`, plugins)
Picocli	4.7.5	Apache 2.0	CLI command framework (`vatn-cli`)
SLF4J	2.0.9	MIT	Logging facade and simple backend (all modules)
SQLite JDBC	3.45.1.0	Apache 2.0	Embedded persistence (`vatn-core`)
PostgreSQL JDBC	42.7.2	BSD 2-Clause	Optional Postgres backend (`vatn-core`)
Flyway Community	10.8.1	Apache 2.0	Database schema migrations (`vatn-core`)
GraalVM SDK	24.1.1	UPL 1.0	Native image C ABI (`vatn-core`, compile-time)

Test and benchmark dependencies

Library	Version	License	Used in
JUnit Jupiter	5.10.0	EPL 2.0	Unit and integration tests
Awaitility	4.2.1	Apache 2.0	Async test assertions
JMH	1.37	GPL v2 + Classpath Exception	Micro-benchmarks (`vatn-bench`)

Note on JMH: JMH is licensed under GPL v2 with the Classpath Exception, which permits use as a tool dependency without GPL propagation to application code. It is used exclusively in vatn-bench and is never shipped as part of the VATN runtime.

Name		Name	Last commit message	Last commit date
Latest commit History 27 Commits
docs		docs
examples		examples
vatn-api		vatn-api
vatn-bench		vatn-bench
vatn-bom		vatn-bom
vatn-cli		vatn-cli
vatn-core		vatn-core
vatn-spec		vatn-spec
vatn-test		vatn-test
vatn-verify		vatn-verify
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
install.ps1		install.ps1
install.sh		install.sh
pom.xml		pom.xml

Folders and files

Latest commit

History

Repository files navigation

VATN — Virtual Application Transaction Node

Why VATN?

Architecture

Installation

Linux / macOS

Windows (PowerShell — run as Administrator)

What the installer does

Installed layout

After installation

Non-interactive / CI install

Plugins

Building your first plugin

Build from Source

Prerequisites

Build the runtime

Build plugins

Deploy your build to the local installation

Build modes

Run the hello-world example

Process Sandbox

Architecture

Trust Levels

Environment isolation (ShellEnvPolicy)

Using VSandboxProvider in your plugin

Querying the audit log

Providing a custom VSandboxProvider

Project Modules

vatn-api — The SPI (Start here)

vatn-core — The Runtime Engine

vatn-cli — Developer Toolbelt

vatn-bench — Benchmarks

examples/ — Working Examples

vatn-test — Plugin Test Harness

vatn-spec — Protocol Specifications

vatn-verify — Protocol Verification Tools

docs/ — Documentation

OIPC Protocol

Federation (v1 now, v2 roadmap)

Performance

Documentation Index

Ecosystem

License

Third-Party Dependencies

Runtime dependencies

Test and benchmark dependencies

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Environment isolation (`ShellEnvPolicy`)

Using `VSandboxProvider` in your plugin

Providing a custom `VSandboxProvider`

`vatn-api` — The SPI (Start here)

`vatn-core` — The Runtime Engine

`vatn-cli` — Developer Toolbelt

`vatn-bench` — Benchmarks

`examples/` — Working Examples

`vatn-test` — Plugin Test Harness

`vatn-spec` — Protocol Specifications

`vatn-verify` — Protocol Verification Tools

`docs/` — Documentation

Packages