Vojeto

Vojeto is a portable, rootless userspace networking companion for connecting unprivileged applications to Nebula-compatible overlays.

The name comes from Esperanto: vojeto means a little path. Vojeto's job is similarly small and deliberate: give an application a path into an existing private mesh without requiring a kernel TUN device, NET_ADMIN, or control of the host network stack.

Important

Vojeto is an independent project. It is not affiliated with or endorsed by Defined Networking or the Nebula project.

Why

Some environments deliberately do not allow privileged networking: managed container platforms, rootless containers, CI workers, restricted Kubernetes workloads, and finite job runners.

Vojeto is intended to make those environments ordinary consumers of an existing Nebula deployment by running entirely in userspace alongside the workload.

The implementation is being extracted from a working prototype originally developed for BiFrost. That prototype already proves:

• Nebula encrypted transport with a gVisor userspace network stack;
• private IPv4 routing through an existing Nebula/Defined router;
• loopback TCP forwarding for PostgreSQL and Redis;
• Managed Defined enrollment;
• exclusively leased identity pools with rotation/checkpointing.

Vojeto additionally implements finite, loopback-only SOCKS5 TCP CONNECT with explicit allowlists, bounded connections, and cancellation; that behavior is covered by Vojeto tests rather than evidence from the current infra prototype.

The extraction will preserve those behaviors while separating portable client functionality from BiFrost-, Azure-, and Defined-specific policy.

Finite peer sessions

make build-peer builds the separate vojeto-peer executable and public peer Go API. It supports an operator loopback forward, a target gateway to one signed IPv4 TCP destination, and an optional isolated lighthouse/relay. Sessions use locally generated endpoint keys and an ephemeral CA, with a maximum 30-minute lifetime. See the session guide for setup, trust boundaries, Windows handling, and Azure lighthouse requirements.

The Linux router launcher adds a bounded mTLS broker API and supervises isolated finite lighthouse child processes. It is opt-in infrastructure; no existing router service is changed automatically.

Architecture direction

application
    |
    | loopback TCP / optional SOCKS
    v
  Vojeto
    |
    | userspace netstack
    v
  Nebula
    |
    v
private overlay

Portable core

The core should own:

• Nebula encrypted transport;
• userspace networking;
• configurable fixed TCP forwarding;
• optional, tightly bounded SOCKS5 TCP CONNECT;
• common lifecycle for long-running services and finite jobs;
• readiness, reconnect, drain, and shutdown behavior;
• health, diagnostics, metrics, and resource limits;
• provider interfaces for identity acquisition, renewal, and release.

Adapters

Cloud and control-plane behavior stays outside the core:

• Defined Networking enrollment and identity management;
• Azure Managed Identity and Storage-backed identity leasing;
• Azure Container Apps replica/job lifecycle integration;
• static or custom identity providers.

Vojeto should remain useful outside Azure and outside containers.

Security posture

Vojeto defaults to the narrowest useful behavior:

• no root requirement;
• no NET_ADMIN;
• no TUN device;
• local application listeners require explicit loopback addresses;
• the separate peer target accepts only its signed operator over the overlay;
• SOCKS is opt-in;
• SOCKS destinations are explicitly allowlisted;
• TCP CONNECT only initially;
• bounded connection counts and timeouts;
• secret-safe diagnostics and logs;
• lease loss must fail closed for new traffic.

Status

An initial runnable extraction is available. Build with make build, verify with make test (race detector), or build a local non-root development container with docker build .. Publication uses docker build --target release ., which collects the complete linked-license bundle and rejects missing licenses; the pinned Defined SDK now includes its MIT license. The separate docker build --target peer-release . inventories only vojeto-peer dependencies and does not link the Defined SDK. Passing that gate is not live deployment proof. The build applies checksum-verified Nebula v1.11.2 patches for packet-cache concurrency and rootless socket-buffer configuration, plus a gVisor retransmission timer patch, in isolated dependency copies. Plain go test ./... does not apply those patches. Linux buffer requests respect the host limits; Vojeto defaults listen.read_buffer to 256 KiB when omitted. The encrypted load-test stall in #14 was corrected and passed 20 repeated encrypted load runs; see the measurement evidence. Live deployment acceptance remains separate.

Run ./vojeto -config /private/nebula.yaml -forwards /private/forwards.json. Configuration contains credentials and must remain private. Forward JSON is an array:

[{"Name":"database","Listen":"127.0.0.1:15432","Target":"192.0.2.10:5432","MaxConnections":32,"DialTimeout":15000000000}]

Durations are currently JSON nanoseconds. Global connections default to 128; -drain-timeout defaults to 30 seconds. SIGTERM/SIGINT stop admission and drain by default. An explicit -signal-grace withdraws readiness while allowing native applications to finish before admission stops; exclusive ownership remains monitored throughout. Explicit completion skips that allowance and starts bounded drain immediately. An optional -control-socket /private/control.sock enables permission-0600 Unix control: POST /v1/lifecycle/complete performs the same bounded shutdown. Use a private parent directory to prevent cross-user socket replacement. Linux finite jobs can instead use -exec -- /absolute/executable ... to start a trusted child after readiness and join network cleanup before exiting; see finite workload supervision.

The CLI accepts static Nebula configuration or a pre-enrolled Defined/Azure Blob identity pool, or a caller-owned local enrollment agent on Linux. Forwarding targets may use numeric IPv4 or names explicitly mapped in the readiness configuration. Unmapped names fail closed. It never falls back to host dialing or modifies system DNS. The opt-in finite SOCKS CLI uses -socks as an alternative to -forwards. Its explicit lifetime completes the portable runtime; listeners and destinations retain the library's narrow security policy. Defined checkpoint/rotation and Azure lease ownership now run through the portable runtime. Lease loss closes admission and active sessions; uncertain credential updates leave the identity quarantined. No automatic takeover or reacquisition is attempted. Pool provisioning and recovery remain operator responsibilities. See leased identity configuration and shutdown.

/live, /ready, and /status are available through the control socket. /status also exposes aggregate process/session counters for resource and leak measurements. Readiness requires successful configured overlay and dependency probes; process startup is not proof of overlay connectivity. Status contains bounded health fields and aggregate counters. See readiness and native drain configuration.

Container runtime: UID 65532, --cap-drop ALL --read-only --security-opt no-new-privileges, no TUN device. Mount secret config read-only; mount a small private writable directory only if using a control socket. No platform-specific support or 64/128/256 MiB memory target is claimed yet.

See extraction boundaries and compatibility.

License

GNU Affero General Public License v3.0. See LICENSE.

Repeatable local resource measurements and their limits are documented in Linux rootless measurements. The image defaults to GOMEMLIMIT=96MiB; this soft runtime limit does not guarantee RSS or prove a platform memory budget. The Defined SDK license was resolved in dnapi#53 and the licensed revision is pinned. Manual publishers require an existing protected release environment, private package access and verified signed OCI evidence. Setup and actual delivery acceptance remain open; see release security. Local build/license success is separate from publication and deployment acceptance.

Defined identity requests use a bounded HTTP adapter with redirect rejection, a 30-second request ceiling and a 2 MiB response limit. Polling failures remain fail-closed by default. Live deployment acceptance and consumer ownership integration remain open; this project is not yet an accepted production replacement. See production acceptance.

Leased providers may opt into finite read-only control-plane outage grace using pollOutageGrace in their provider JSON. The default stays fail-closed. This never covers uncertain rotation or lease loss; see the outage policy.

A fresh enrollment provider accepts externally fenced one-time grants through library interfaces. It validates the candidate and checkpoints it before transport starts. The Linux defined-external-agent CLI carries this contract over a private Unix socket; concrete broker adapters and durable ownership proof remain consumer integration work. Existing pooled CLI behavior is unchanged.

Managed route rotation compares exact route entries independently of their list order. Adding, removing or changing a route, gateway or attribute still requires review; duplicate multiplicity remains significant. Credentials are checkpointed before validating a rotated configuration, and the configuration is checkpointed before reload.

CLI startup failures emit only bounded source-owned codes, such as identity-acquisition, route-change, nebula-initialization or startup-readiness. Private configuration, upstream response text and unknown error details remain suppressed. A diagnostic code does not authorize recovery or reuse of a quarantined identity.