vinculum

Vinculum

"The [vinculum is the] processing device at the core of every Borg vessel. It interconnects the minds of all the drones." -- Seven of Nine (In Voyager episode "Infinite Regress")

Vinculum is a low-code system for gluing together different systems and bridging multiple protocols. Think of it as a Swiss Army Knife for communications: while not the best tool for demanding tasks where you'd want a purpose-built solution, it handles a large variety of integration tasks adequately — letting you quickly MacGyver together a solution with a few lines of configuration.

Getting Started

Vinculum is designed to be deployed as a container. Run the published image, mounting a directory of .vcl config files at /conf (the image's default command is serve … /conf):

docker run --rm -p 8080:8080 -v "$PWD:/conf:ro" ghcr.io/tsarna/vinculum:latest

To try it with no setup, point it at the credential-free weather-mcp example, which stands up an MCP server you can connect Claude Desktop or Claude Code to:

git clone https://github.com/tsarna/vinculum
docker run --rm -p 9000:9000 -v "$PWD/vinculum/examples/weather-mcp:/conf:ro" \
    ghcr.io/tsarna/vinculum:latest

See examples/ for more (including the traffic-light intersection modeled entirely in config), doc/container.md for image tags and mount points, and doc/overview.md for the full reference.

Pull configuration from git

You don't have to bake config into the image. Drop a small .vinit bootstrap file into /conf (e.g. via a Kubernetes ConfigMap) and Vinculum will clone a pinned revision of a repository and materialize it before any .vcl is parsed. For instance, this deploys the traffic-light example straight from this repo:

# /conf/bootstrap.vinit

git "traffic_light_example" {
    repo   = "https://github.com/tsarna/vinculum.git"
    branch = "main"

    fetch "traffic_light" {
        from      = "examples/traffic-light"
        into      = "/conf/git/traffic-light"
        overwrite = true
    }
}

The fetch is pure Go, so it works even in the scratch-based minimal image, which has no git binary or shell. See doc/git.md for authentication, revision pinning, and multi-subtree fetches.

Key Features

• HCL Configuration — Declarative configuration in HashiCorp Config Language (similar to Terraform), with constants, expressions, and assertions
• Git-Sourced Configuration — Pull configuration (and static assets, MCP resource files, etc.) from a pinned revision of a git repository at startup, instead of baking it into the image — pure-Go, so it works even in the scratch-based minimal image
• Publish/Subscribe Messaging — One or more event buses with MQTT-style topic routing, wildcards, and parameter extraction
• Server Protocols — HTTP(S), Vinculum WebSocket (VWS), plain WebSocket, Model Context Protocol (MCP), and Prometheus/OpenMetrics, all with pluggable authentication (basic, OIDC, OAuth2)
• Client Protocols — HTTP(S), Kafka, MQTT, RabbitMQ (AMQP 0-9-1), Redis/Valkey (pub/sub, streams, key-value), AWS SQS, AWS SNS, VWS (to other Vinculum instances), OpenAI / LLM, and OpenTelemetry (OTLP) export
• SQL Databases — Query PostgreSQL, MySQL, and SQLite from config via the polymorphic get() / call() functions, with named queries, positional and named parameters, and structured result objects; Postgres and MySQL are pure-Go (no cgo)
• Triggers — A range of trigger types for time-, event-, and lifecycle-driven actions: cron, dynamic intervals with optional jitter, absolute / dynamic times including sunrise/sunset, file-system events, OS signals, startup/shutdown, watchdogs, and watches over reactive values
• Conditions — Named boolean primitives with temporal rules (activate/deactivate delays, hysteresis, retentive timing, latches, cooldown, inhibit), covering IEC 61131-3 timer and counter function-block behaviors and composable into pipelines
• State Machines — Finite state machines with guarded transitions, reactive events, key-value storage, MQTT topic matching, and OpenTelemetry tracing; composable with conditions and watchable for reactive integration
• Transformations and Scripting — JQ-based message transforms, structured-text editor blocks, and functy (.cty) files: a small imperative language with functions, typed locals, control flow, and structured errors
• Built-in Functions — A large standard library covering HTTP, files, templates, time, randomness, IDs, LLMs, sunrise/sunset, geographic calculations, and more.
• Plugins — Load Go shared-object plugins (.so) at startup to extend Vinculum with custom functions, transforms, server/client/trigger types, and more — using the same registration points as in-tree subsystems
• Observability — Context propagation, OpenTelemetry tracing and metrics, and Prometheus support baked in and trivial to configure.
• Interactive REPL — serve -i drops into a prompt that evaluates VCL expressions against the live, running configuration — read state, call functions, and send messages to real buses, with result history and tab completion

Documentation

See doc/overview.md for full documentation including:

• Core concepts (buses, topics, subscribers, transformations)
• Configuration language reference
• Protocol details
• Examples

Examples

The examples/ directory contains complete working configurations. See examples/README.md for the index, including a dynamic DNS zone updater that combines an HTTP server, basic authentication, a functy function, and a line-editor block to safely rewrite BIND zone files.

Related Projects

Vinculum is built on top of several standalone Go libraries that can be used independently:

Vinculum also relies on several smaller standalone HCL/cty helper libraries: go2cty2go, hcl-jqfunc, go-structdiff, rich-cty-types, bytes-cty-type, url-cty-funcs, time-cty-funcs, rand-cty-funcs, sqid-cty-funcs, geo-cty-funcs, and barcode-cty-func.

License

Apache License 2.0 - see LICENSE file for details.

Vinculum (Latin: "bond" or "link") — connecting your systems with reliable, configurable messaging.