§ 03 — why this exists

Eight things that are uncommon, together.

Most agent platforms pick one of three shapes — a library you embed, a hosted service you rent, or a gateway that doesn't run the loop. loomcycle is something different: a self-hostable runtime that owns the loop, speaks every wire surface (HTTP, gRPC, MCP, TS adapter, OpenAI-compat), and stays out of your application's process.

01

One Go binary. ~30 MB resident.

No Node, no Python, no JVM, no vendor SDK in the model path. Drop it in alongside your application and forget it's there.

02

The loop runs outside your app process.

Most agent frameworks make you embed them — your application becomes their language whether you wanted that or not. loomcycle is a sidecar; your application stays in whatever you wrote it in. Talk to it over HTTP, gRPC, MCP, or via the TypeScript adapter.

03

MCP client and MCP server, simultaneously.

Agents you host are reachable as MCP tools from outside; tools outside are mountable as MCP servers inside. Most products are one side of the protocol; loomcycle is both.

04

OpenAI-compatible gateway + native gateway + agent loop in the same process.

Point existing OpenAI-shaped code at loomcycle by changing one base URL — and you've also installed an agent runtime. One auth surface, one audit log, one quota system across both.

05

A real UNIX-style trust model.

Operator config is the floor; callers can narrow per-request but never widen. Bearer auth at the HTTP frontier. Posture A (default-deny sandbox) vs Posture B (operator-trusted dev) selected via env. Per-tenant fairness on the run-admitting semaphore.

06

Content-addressed agent definitions.

AgentDef, SkillDef, MCPServerDef — three substrate tables, each row hashed by SHA-256 over its content fields. Push definitions at boot from your application's image. Verify-or-fork across container walls. Audit the exact version of an agent that ran.

07

Anthropic MAX subscription OAuth for dev work.

Local development can run against your Claude MAX subscription instead of pay-per-token API. Reverse-engineered integration — no Anthropic warranty, dev-only, opt-in. Full disclaimer on GitHub →

08

Self-hostable, Apache-2.0, no cloud dependency.

Pause / Resume / Snapshot for in-place upgrades (shipped). Multi-replica HA via Redis cancel pubsub on the way. The runtime grows from a single replica on a cheap VPS to many machines without changing shape.

Sidecarthe runtime view GatewayOpenAI-compat view MCP-nativeprotocol view

The agentic loop, in a sidecar.

Drop one Go binary alongside your application. Get a hardened loop, memory, channels, MCP on both sides, OpenTelemetry everywhere — without adopting a framework's language or a cloud's lock-in.

When you ship an agentic feature, the default options are all uncomfortable. Embedding an in-process Python or TypeScript framework means your application becomes that framework's shape, whether you chose Python for it or not. Adopting a hyperscaler's managed agent service means inheriting their IAM, their billing, their model catalog, and their idea of what an agent should look like — and migrating off later is its own multi-quarter project. Building the loop yourself means six months of writing memory, channels, hook contracts, OpenTelemetry propagation, per-tenant fairness, and an agent-definition substrate before you ship a single agent.

loomcycle is the sidecar that ends that tradeoff. One Go binary, around 30 megabytes resident, no SDK in your code path. You call it over HTTP, gRPC, MCP, or via the TypeScript adapter — whichever fits your stack. The agentic loop lives inside loomcycle; your application stays in whatever language you wrote it in. Memory, Channel, AgentDef, SkillDef, MCPServerDef, the Pre/Post hook contracts — all shipped primitives, not exercises for the reader.

The runtime grows from a single replica on a cheap VPS to multi-replica HA without changing shape. Pause / Resume / Snapshot for in-place upgrades is shipped. Per-tenant fairness on the run-admitting semaphore is shipped. OpenTelemetry traces span the whole loop — providers, tools, MCP servers, hook callbacks. Six model providers behind a native HTTP interface, no vendor SDK in the loop. The infrastructure you would otherwise build before writing your first agent — already built, Apache-2.0 licensed, ready to drop in.

Read the architecture → Quickstart →

An OpenAI-compatible gateway that also runs agents.

If you already proxy LLM calls through a gateway for cost, routing, or audit, you're already paying for half of what loomcycle does. Get the agent loop in the same process.

Most production teams arrive at LLM gateways the same way. You start with one model provider. You add a second for cost arbitrage or fallback. You want one auth surface, one audit log, one quota system across both. You install a gateway, point your OpenAI-shaped client code at its base URL, and it works. Then you decide to ship an agentic feature — tool calls, multi-step reasoning, memory, MCP — and you realise your gateway can't do that, your framework choice can't run cross-tenant, and gluing the two together is a multi-month project before your first agent ships.

loomcycle speaks OpenAI's wire format. POST /v1/chat/completions and POST /v1/embeddings are both there. Point your existing LangChain code, RAG pipeline, vector DB embedder, or any tool that defaults to OpenAI at loomcycle by changing one base URL and one auth token. Behind that familiar wire format sits a multi-provider resolver, per-tenant quotas, host allowlist enforcement, OpenTelemetry traces, and an audit log. So far this is just a better gateway.

The same binary also runs agents. The same auth surface, the same quota, the same audit log, the same OpenTelemetry spans cover both the proxied chat completions and the agent runs. When the moment comes that you need an agentic feature, you don't add a second service — you light up the loop that was always there. Tool calls via MCP. Memory with vector search. Channels for inter-agent coordination. Pre/Post hooks at every tool boundary. A content-addressed substrate for agent and skill definitions. All in the binary you already deployed for the gateway story.

Read the gateway architecture → Quickstart →

The MCP runtime that sits on both sides of the protocol.

Most products consume MCP servers as tools. Some expose themselves as MCP servers. loomcycle does both — simultaneously, on the same auth surface, in the same process.

MCP is consolidating into the protocol that agentic systems will speak by default. Every major model vendor now ships MCP support on their agent surface. The stateless, OAuth-aligned core of the protocol means MCP servers can be authenticated, audited, and composed the way HTTP services already are. The shape of agent tool use over the next several years is being settled in committee right now — and the answer is, increasingly clearly, "tools are MCP servers."

loomcycle was built to be a citizen of that protocol on both sides. As an MCP client: mount any MCP server as a tool the model can call, with per-server bearer auth, host allowlist enforcement, and the same Pre/Post hook contracts that govern every other tool. Dynamic MCPServerDef registrations land in the substrate the same way agents and skills do. As an MCP server: loomcycle's agents, channels, memory, and substrate operations are themselves addressable from outside via MCP — Claude Code, external orchestrators, or any MCP-aware client can drive them. The dual posture is rare; it's the difference between consuming the protocol and speaking it fluently.

The MCP runtime story compounds with the rest of the loomcycle architecture. Per-tenant fairness applies to MCP-driven runs the same way it applies to HTTP-driven ones. The content-addressed AgentDef / SkillDef / MCPServerDef substrate means MCP tool surfaces can be versioned, signed, and pushed at boot. The Pre/Post hook contract — including content-scrubbing on attacker-controllable tool results — applies to MCP-mounted tools without special-casing. If you're already building on MCP, or expecting your stack to converge on it as the standard, this is the runtime that grew up around it.

Read the MCP architecture → Quickstart →

§ 04 — what this is not

What loomcycle is not.

A short, candid section. If your situation matches any of these, you'll save time by picking a different tool — and we'd rather route you to the right one than waste your day.

Not a Python or TypeScript framework you embed. If you want a library that lives inside your app's process and gives you an agent abstraction at the function-call level, you don't want loomcycle — you want a framework, and there are good ones. loomcycle is the runtime under that framework, or the runtime instead of it.

Not a no-code builder. If you want to drag boxes onto a canvas and connect them with arrows, you don't want loomcycle — you want a visual workflow tool. loomcycle plugs into one of those tools as a node provider (the community package is shipped), but loomcycle itself is not the canvas.

§ 05 — primitives

The five primitives that make agentic systems learnable.

Memory and Channel are the substrate. AgentDef and Evaluation are the self-evolution loop. Context is the introspection primitive that closes it.

Memory

shipped v0.8.0

Persistent state per agent or per user. Atomic incr. TTL. Cross-run continuity that survives process restarts.

// set a memory key
{"tool":"memory",
 "input":{"op":"set",
         "scope":"user",
         "key":"last_seen",
         "value":"…"}}

Channel

shipped v0.8.4

Persistent inter-agent message bus. One agent publishes; another subscribes; no orchestrator handoff. Cursor-based delivery.

// publish to a channel
{"tool":"channel",
 "input":{"op":"publish",
         "name":"jobs.scored",
         "payload":{...}}}

AgentDef

shipped v0.8.5

Agents fork themselves into versioned definitions with lineage tracking. The substrate for self-evolution.

// fork a new definition
{"tool":"agentdef",
 "input":{"op":"fork",
         "from":"matcher.v4",
         "prompt":"…"}}

Evaluation

shipped v0.8.5

Rate runs against versioned definitions. Selection stays policy — never auto-promote. Humans (or downstream agents) choose.

// score a run
{"tool":"evaluation",
 "input":{"op":"score",
         "run":"r_82a1",
         "rubric":"match.v2"}}

Context

shipped v0.8.7

The introspection primitive. Ten ops covering self · tools · agents · history · help. The closing loop that makes the substrate learnable — an agent that can read itself can rewrite itself.

// what tools do I have?
{"tool":"context",
 "input":{"op":"tools"}}    // → list with shapes, costs, allowed-hosts

§ 06 — trust model

Same binary. Two postures. The operator picks via env.

The UNIX shape you already know — operator, caller, agent. Operator config is the floor; callers can narrow per-request but never widen. The bearer token is the authority.

posture A

True managed sandbox

Default-deny every tool
No FS roots
No Bash
Caller-authoritative allowed_hosts
No outbound by default

Shared-server deployments processing untrusted input. Multi-tenant SaaS. Anywhere the caller isn't the operator.

posture B

Agentic dev environment

Bash on, scoped FS roots
Broad allowed_hosts
Local Ollama for offline work
Operator-trusted tooling
Iteration speed prioritized

Local development. Internal trusted operators. The single-machine workflow where you are the caller.

§ 07 — providers

Six providers. One interface. No vendor binary in the loop.

Resolver picks (provider, model) per tier and effort. Cross-provider fallback with reasoning_content strip. Cache_control where supported. Native HTTP-only.

Anthropic

OpenAI

DeepSeek

Gemini

Ollama (cloud)

Ollama (local)

// Provider interface

caps:cache_control · reasoning · tools

resolve:(tier, effort) → (provider, model)

fallback:on 429 · strip reasoning_content

pin:v0.8.13 · pin-after-success

→ Pin-after-success ends the transcript-translation bug class. Cache_control where supported. No bundled SDK.

+ OpenAI-compatible front door — POST /v1/chat/completions and POST /v1/embeddings on top of the same resolver / quota / audit layer. Drop loomcycle in front of any LangChain, LlamaIndex, n8n Chat Model, or RAG pipeline that already speaks OpenAI's wire format. Read the writeup →

⚠ Dev-only: Anthropic MAX subscription OAuth. Sign in with your Claude MAX subscription; local agent runs use subscription-priced inference instead of pay-per-token API. The integration is reverse-engineered (originally by the Pi agent team) — see the full disclaimer and operator setup guide on GitHub → before enabling.

§ 08 — recently shipped

What landed in v0.9 — v0.11.

Six weeks. Three sub-version families. Most of v1.0's surface area is now in place — what's left is hardening, distribution polish, and one big multi-replica HA milestone.

Dynamic substrate

v0.8.5 → v0.9.x

AgentDef, SkillDef, and MCPServerDef — three substrate tables, each content-addressed by SHA-256, runtime-mutable, pushed at boot from the consumer's image. Library v2 UI surfaces them with STATIC / DYNAMIC chips. writeup →

Vector Memory

v0.9.0

Semantic search on the Memory tool. embed: true on writes; search: { query, top_k } on reads. sqlite-vec on the storage side; Voyage / OpenAI / Cohere / nomic-embed on the embedding side. Same provider as the embeddings shim.

OTel everywhere

v0.10.0

Distributed traces across loop + providers + tools + MCP. Span propagation through Pre / Post hooks. If you're running Tempo or Honeycomb, every agent run now appears with one trace and per-step children.

Per-tenant fairness

v0.10.1

The run-admitting semaphore is now per-tenant. A noisy customer can't starve a quiet one of LLM-call budget. Pairs with the per-user quota tracking that lives on every front door (native + OpenAI-shim).

LLM Gateway + OpenAI shims

v0.11.0 → v0.11.4

Three front doors, one engine. POST /v1/_llm/chat for loomcycle-native consumers; POST /v1/chat/completions + POST /v1/embeddings for everything that defaults to OpenAI. Resolver + quota + audit + host-allowlist applied uniformly. writeup →

n8n community package

v1.0.0 → v1.2.0

@loomcycle/n8n-nodes-loomcycle. Five cluster sub-nodes (incl. a LangChain Chat Model wired to the gateway). Action nodes for Run / Memory / Channel + AgentDef / SkillDef / MCPServerDef. RunCompleted + ChannelMessage triggers. Six example workflows. writeup →

Pre / Post hooks

v0.8.17 → v0.8.18

Per-call URL widening on the way in; LIFO PostTool output rewriting on the way out. The PostTool contract is what the JobEmber content scrubber sits on — sixteen injection patterns redacted before the model sees them. writeup →

Distribution surface

v0.10.2 → v0.11.2

Docker image, Homebrew tap with auto-bump, Goreleaser cross-platform binaries, signed npm + PyPI publishes on tag, ESM + CJS adapter builds. loomcycle init / loomcycle doctor / config auto-discovery for first-touch users.

Parallel sub-spawn

v0.11.7 → v0.11.8

Agent.parallel_spawn with a per-agent max_concurrent_children cap. Theming and warning placement polish in the Web UI, publish-workflow polish in CI.

Anthropic MAX OAuth (dev)

v0.11.10 → v0.11.11

Dev workflow can run against your Claude MAX subscription instead of pay-per-token API. Three subcommands: loomcycle anthropic login / status / logout. Reverse-engineered integration with explicit no-warranty terms — full disclaimer on GitHub →

Pause / Resume / Snapshot

v0.8.17 → v0.8.18

Runtime-wide quiesce + cross-version-portable JSON snapshot. Restore on a different binary version. The precondition for multi-replica HA. Cross-transport hardened in v0.8.18 so MCP, gRPC, CLI, and the TypeScript adapter all hit the same real implementation.

Interruption tool

v0.8.16

Human-in-the-loop primitive. Three ops (ask / notify / cancel), three delivery backends (Web UI default, consumer-side MCP, CLI). Signals flow through _system/interrupts/* channels. Agents pause cleanly on uncertainty instead of confabulating.

§ 09 — from runtime to Agentic OS

How loomcycle became what it is.

Loomcycle started solving two problems. Scale — jobs-search-agent runs ~500 concurrent agentic sessions, and vendor SDKs that spawn a Claude Code process per session blow memory past 25 GB. A cost runaway we triggered ourselves — during loomcycle's own early prototype, we spawned ~100 claude code --print instances as prompt-injection-detection fallbacks; the processes inherited ANTHROPIC_API_KEY from the shell env, ran Opus 4.7 in parallel, and burned real money before we caught it.

The lightweight runtime that solved both measures 30–60 MB resident. Goroutine-per-session beats process-per-session by four orders of magnitude on memory. We could have stopped there.

We didn't. After a long architecting and implementation run (me + Claude Opus as architectural collaborator), loomcycle is now a lightweight Agentic OS — sandboxed sidecar OR an agentic runtime orchestrated by Claude Code via MCP. Runs big interconnected agent teams. Generates and reacts to internal + external events. Self-educates and self-evolves. Snapshots at any stage and resumes later. Long-running experiments. Community-shareable results.

One Go binary. No subprocess in the hot path. Whole bug class — structurally gone.

Read the architecture →

§ 10 — quickstart

Three commands. One curl. One Web UI link.

Self-host on a single replica in under three minutes. Homebrew (brew install denn-gubsky/loomcycle/loomcycle), Docker (ghcr.io/denn-gubsky/loomcycle), or from source. loomcycle init generates a starter config; loomcycle doctor checks your provider keys.

~/loomcycle · zsh

// build & configure

$ make build-all $ cp .env.example .env.local # set ANTHROPIC_API_KEY / etc. $ cp loomcycle.example.yaml ~/.config/loomcycle/loomcycle.yaml $ ./bin/loomcycle --config ~/.config/loomcycle/loomcycle.yaml

// health check

$ curl http://127.0.0.1:8787/healthz {"ok":true}

// first real call

$ curl -N http://127.0.0.1:8787/v1/runs \ -H "Authorization: Bearer $LOOMCYCLE_AUTH_TOKEN" ...

// open the Web UI

$ open "http://127.0.0.1:8787/ui?token=$LOOMCYCLE_AUTH_TOKEN"

// optional: dev workflow on MAX subscription (reverse-engineered — see docs/PROVIDERS.md)

$ loomcycle anthropic login # browser OAuth flow $ loomcycle anthropic status # check current session $ loomcycle anthropic logout # revoke when done

§ 11 — roadmap

Honest. Dated. Trigger-based.

No "Q3 2026" calendar guessing — versions and triggers. Each line has a concrete what and a concrete why. The list below shows the runway from the current v0.11.x line through the v1.0 launch milestone.

v0.11.12● shipped

Current — Hash CLI yaml-name mode, Channels UI source-tag filters

Two small DX items bundled. loomcycle hash agent --config <yaml> <name> extends the v0.9.x path-mode hash CLI with a name-lookup mode for pre-deploy AgentDef drift detection. Web UI Channels view gains yaml / runtime / orphan source-tag filter chips. Lands on top of v0.11.10–v0.11.11 (Anthropic MAX OAuth disclaimer hardening), v0.11.8 (Agent.parallel_spawn), and v0.11.6 (Library admin v2).

v0.12▶ in flight

Multi-replica HA — the final v1.0 prerequisite

Redis cancel pubsub. Cross-replica run-affinity routing. In-memory run-status cache. Heartbeat-sweeper hardening. With Pause / Resume / Snapshot (v0.8.17) shipped, per-tenant fairness (v0.10.1) shipped, and OpenTelemetry (v0.10.0) shipped, the remaining work is the cross-process coordination surface. The single-binary scaling story from a cheap VPS to many machines completes here.

v0.12next

n8n cloud verified-list submission

Self-hosted n8n works today via the community-node install. n8n cloud's verified-list policy is stricter; submission is mid-flight. Same package, broader audience.

v1.0launch

Stable contributor surface + Helm + operator cookbook

Helm chart for Kubernetes deployments. Operator cookbook covering the canonical postures and scaling patterns. Settings UI completion. External code contributions open here.

past● shipped

Already landed (v0.8 → v0.11)

Self-evolution substrate (AgentDef/SkillDef/MCPServerDef, content-addressed by SHA-256) · System channels + deferred publish · Context introspection tool · Process-resource metrics · LoomCycle MCP server (loomcycle exposes itself as MCP) · Pause / Resume / Snapshot · Interruption tool (human-in-the-loop) · Cross-transport hardening · Library v2 STATIC/DYNAMIC chips · OpenTelemetry across loop+providers+tools+MCP · Per-tenant fairness · Vector Memory · sqlite-vec + Voyage embedder · LLM Gateway · OpenAI Chat Completions + Embeddings shims · yaml-static channels + memory · Library admin v2 · Multi-agent fan-out (Agent.parallel_spawn) · Anthropic MAX OAuth (dev-only, reverse-engineered) · @loomcycle/n8n-nodes-loomcycle · ESM+CJS adapter · cross-platform binaries · Homebrew tap · Docker image · loomcycle init / doctor. Full per-version log: REVISIONS.md.

§ 12 — talk to us

Building on loomcycle, or thinking about it?

We'd like to hear what you're building. Production users inform v1.0 design, and integration-shape ideas are the things that get RFCs written. No sales process, no NDA, no waitlist — just a real conversation about whether loomcycle fits your shape.

[email protected]

Public alternative: github discussions → · Security disclosures: [email protected]

The Agentic OS, in a sidecar.