Vinculum

Why Vinculum

Drones that remember.

Spinning up a fresh pod for every prompt is wasteful. Vinculum runs each Agent as a long-lived pod with an open crush session and a persistent workspace - so context survives, PVCs survive, and cold-start disappears.

⟳

Long-lived sessions

A pod per Agent - no per-prompt cold-start. Crush session + /workspace PVC survive restarts.

☸

Kube-native

Declarative Agent, Task, AgentSchedule, MCPServer CRDs. One operator reconciles them into Deployments, PVCs, RBAC, Services.

◎

Multi-provider

Azure OpenAI, Anthropic, OpenAI, or bring-your-own - a provider is just a labeled Secret.

▸_

One-binary CLI

Port-forwards through your active kubecontext - no exposed operator endpoint, no long-lived local state.

Custom Resources

Declare it. The hive complies.

Six CRDs. Everything else is derived.

Agent

Long-running agent drone. Model, provider secret ref, instructions, workspace size, attached MCP servers, orchestrator + peer flags. Operator creates Deployment, Service, PVC, RBAC.

Task

A unit of work. Prompt, fresh, workspace mode (shared or ephemeral), timeout, artifacts, env. Serial execution per Agent.

Message

Async chat between Agents. to, body, optional inReplyTo for threads. Browsable via kubectl get messages — replies arrive as new Messages, not return values.

AgentSchedule

Cron trigger that stamps Tasks from a template. Concurrency policy: Allow, Forbid, Replace.

MCPServer

Reusable Model Context Protocol server - stdio or http. Attach by name to any Agent. secretRef wired as envFrom.

WebhookTrigger

Inbound GitHub webhooks turned into Tasks. HMAC-verified, event/branch-filtered, with ${event.*} template substitution into the rendered Task.

Initiation protocol

Five steps to assimilation.

Any Kubernetes cluster. Any active context. Helm chart + Homebrew CLI.

Install the chart

Helm OCI install - no repo add, no values overrides required for a default run.

helm install vinculum oci://ghcr.io/florianwenzel/helm/vinculum \
  --version 0.6.0 \
  -n vinculum-system --create-namespace

Install the CLI

Homebrew tap for macOS + Linux. Prebuilt binaries available for all platforms on every release.

brew install FlorianWenzel/vinculum/vnclm

Create a provider Secret

Drop API keys into a labeled Secret. Wizard handles the labeling + encoding.

vnclm create provider # interactive wizard

Create an Agent

Pick a model, point at a provider, optionally attach MCP servers. Operator provisions the pod.

vnclm create agent # wizard

Run a Task

Streams live. Blocks until terminal phase. Run again later - crush picks up the session, history intact.

vnclm ctx set-agent locutus
vnclm run "Compose a haiku about the Borg collective."

Cybernetic implant

Drones that ship code.

Declare a repo on the Agent and a branch / PR on the Task. The operator clones on pod start; the agent wraps each crush run with the git workflow — fetch, branch, commit, push, and (for GitHub) open a PR via the REST API.

spec.repo: Operator adds a git-clone init container that hydrates /workspace/<path> on pod start. Cached on the PVC; restarts just git fetch --prune.
spec.gitCredentials: Reference Secrets for an SSH deploy key (id_ed25519) and/or an HTTPS token. Either, both, or neither.
Task.spec.git: baseBranch, headBranch, commitMessage, prTitle, prBody, skipPR — all optional, sensible defaults.
NoChanges short-circuit: If crush touches no files, the Task ends Succeeded with reason=NoChanges. No branch, no commit, no PR — no noise.

Wire up + run, declaratively yaml

# Agent — clones acme/api on pod start, authenticates with a PAT
apiVersion: vinculum.dev/v1alpha1
kind: Agent
metadata:
  name: coder
spec:
  model: openrouter/anthropic/claude-sonnet-4.6
  providerSecretRef: { name: openrouter-provider-keys }
  repo:
    url: https://github.com/acme/api.git
    branch: main
    path: app
  gitCredentials:
    tokenSecretRef: { name: acme-github-pat }
    userName: "Vinculum Bot"
    userEmail: "bot@acme.test"
---
# Task — implement a feature, ship a PR
apiVersion: vinculum.dev/v1alpha1
kind: Task
metadata:
  name: add-v2-health
spec:
  agentRef: coder
  prompt: "Add a /v2/health endpoint that returns {status:'ok'}."
  git:
    baseBranch: main
    headBranch: feat/v2-health
    commitMessage: "feat: add /v2/health endpoint"
    prTitle: "Add /v2/health endpoint"

Or from the CLI vnclm run "implement /v2/health" --base-branch main --head-branch feat/v2-health --pr-title "Add /v2/health". skipPR: true commits + pushes without opening a PR — for GitLab / Bitbucket / self-hosted hosts.

Hive mind

Drones that command drones.

Flip orchestrator: true on any Agent and it becomes a master. A stdio MCP server baked into the image — vnclm-mcp — wires the operator's in-cluster API into the running crush session, so the LLM can decompose work and farm it out to peer drones.

list_agents: Enumerate the collective. Name, model, phase, readiness.
dispatch_task: Create a Task against a peer Agent. Returns the new Task name immediately. Refuses self-dispatch.
get_task: Read the current phase plus stdoutTail / stderrTail / exitCode.
wait_task: Block until Succeeded / Failed / TimedOut, or hit timeoutSeconds.
get_task_logs: Stream the peer pod's recent crush output for a Task.
cancel_task: Delete a Task. Cancels in-flight execution.

Declare a master + worker yaml

# bundled stdio MCP — the binary ships in the agent image
apiVersion: vinculum.dev/v1alpha1
kind: MCPServer
metadata:
  name: vinculum
spec:
  command: vnclm-mcp
  enabled: true
---
# worker — runs whatever locutus delegates to it
apiVersion: vinculum.dev/v1alpha1
kind: Agent
metadata:
  name: drone-7
spec:
  model: openrouter/anthropic/claude-haiku-4.5
  providerSecretRef: { name: openrouter-provider-keys }
---
# master — orchestrator flag flips on VINCULUM_OPERATOR_URL + the MCP
apiVersion: vinculum.dev/v1alpha1
kind: Agent
metadata:
  name: locutus
spec:
  orchestrator: true
  model: openrouter/anthropic/claude-sonnet-4.6
  providerSecretRef: { name: openrouter-provider-keys }
  mcpServerRefs: [vinculum]

Trust boundary The operator's in-cluster API has no auth — the namespace is the trust boundary. The orchestrator flag gates env injection, not network reachability. Isolate orchestrators in their own namespace when stricter separation matters.

Lateral subspace

Drones that confer.

Orchestrators dispatch work. Peers exchange messages. Every Agent ships with peer: true by default — the bundled MCP exposes a tiny async chat surface so a dev drone can ask a PO drone "how should I proceed?" or a QA drone can poke a dev drone about its PR. Conversations are first-class K8s resources: kubectl get messages lists every back-and-forth, and replies thread via inReplyTo.

send_message: Async send to a named peer. Returns immediately with the new Message name. Pass inReplyTo to thread; pass name to control the resource ID.
list_peers: Enumerate peer Agents (excluding self) — name, model, readiness, plus any vinculum.dev/role label.
get_message: Read a Message by name. status.replyMessages lists every Message that set inReplyTo to it — the thread, both directions.

Two peers, one bundled MCP, no orchestrator required yaml

# Bundled vinculum MCP — wires send_message into each drone's crush session
apiVersion: vinculum.dev/v1alpha1
kind: MCPServer
metadata: { name: vinculum }
spec: { command: vnclm-mcp, enabled: true }
---
# peer: true is the schema default — no orchestrator flag needed
apiVersion: vinculum.dev/v1alpha1
kind: Agent
metadata: { name: dev-7 }
spec:
  model: openrouter/anthropic/claude-sonnet-4.6
  providerSecretRef: { name: openrouter-provider-keys }
  mcpServerRefs: [vinculum]
---
apiVersion: vinculum.dev/v1alpha1
kind: Agent
metadata: { name: qa-3 }
spec:
  model: openrouter/anthropic/claude-haiku-4.5
  providerSecretRef: { name: openrouter-provider-keys }
  mcpServerRefs: [vinculum]

Async by design No await_reply. When peer-b replies to peer-a's message, the reply lands as a fresh inbound Message that fires a new crush turn on peer-a — the way a teammate's Slack ping wakes you up. To opt out entirely, set peer: false on the Agent.

Subspace beacon

Drones that wake on signal.

A WebhookTrigger turns inbound GitHub webhooks into Tasks. The operator verifies the HMAC signature against a per-trigger Secret, matches the event against your filter, substitutes ${event.*} placeholders into the task template, and stamps the Task. Open a PR — your review agent commits its read.

Autonomous PR review on every push yaml

apiVersion: vinculum.dev/v1alpha1
kind: WebhookTrigger
metadata:
  name: acme-pr-review
spec:
  source: github
  events: [pull_request.opened, pull_request.synchronize]
  filter:
    repo: acme/api
    branch: main
  secretRef: { name: acme-gh-webhook }   # key "secret" = HMAC shared secret
  agentRef: coder
  taskTemplate:
    prompt: "Review PR #${event.pr.number} (${event.pr.title})."
    fresh: true
    git:
      baseBranch: ${event.pr.head}
      headBranch: review/pr-${event.pr.number}
      prTitle: "review: PR #${event.pr.number}"

Exposure The operator's /webhook/github is on the same in-cluster Service as the rest of the API. Wire your own Ingress / tunnel / LB — vinculum doesn't bake one in so you stay in control of TLS, hostnames, and any extra auth.

Tool assimilation

MCP servers as first-class drones.

Give agents extra tools by declaring MCPServer resources - stdio processes or HTTP endpoints - and attaching them by reference. One MCPServer, many agents.

Attach a filesystem MCP to every agent that needs it zsh

# stdio MCP - filesystem over the agent's /workspace PVC
vnclm create mcp --name filesystem --command npx \
  --arg -y --arg @modelcontextprotocol/server-filesystem --arg /workspace \
  --enabled

# http MCP with a secret injected as envFrom
vnclm create mcp --name github --url https://api.githubcopilot.com/mcp/ \
  --secret-ref github-mcp --enabled

vnclm create agent   # wizard → multiselect attaches MCPs

The collective
for AI coding agents.

Drones that remember.

Long-lived sessions

Kube-native

Multi-provider

One-binary CLI

Declare it. The hive complies.

Agent

Task

Message

AgentSchedule

MCPServer

WebhookTrigger

Five steps to assimilation.

Install the chart

Install the CLI

Create a provider Secret

Create an Agent

Run a Task

vnclm - the command link.

Drones that ship code.

Drones that command drones.

Drones that confer.

Drones that wake on signal.

MCP servers as first-class drones.

The collectivefor AI coding agents.

Drones that remember.

Long-lived sessions

Kube-native

Multi-provider

One-binary CLI

Declare it. The hive complies.

Agent

Task

Message

AgentSchedule

MCPServer

WebhookTrigger

Five steps to assimilation.

Install the chart

Install the CLI

Create a provider Secret

Create an Agent

Run a Task

vnclm - the command link.

Drones that ship code.

Drones that command drones.

Drones that confer.

Drones that wake on signal.

MCP servers as first-class drones.

The collective
for AI coding agents.