Show HN: Loomcycle – a sidecar runtime for AI agents (Go binary, Apache-2.0)

Notifications You must be signed in to change notification settings

Fork 0

Star 9

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

618 Commits

618 Commits

.github

.github

adapters

adapters

bench

bench

cmd/loomcycle

cmd/loomcycle

docs

docs

examples

examples

internal

internal

proto

proto

test

test

web

web

.dockerignore

.dockerignore

.env.insecure.example

.env.insecure.example

.env.local.example

.env.local.example

.gitignore

.gitignore

.goreleaser.yaml

.goreleaser.yaml

BACKERS.md

BACKERS.md

CLAUDE.md

CLAUDE.md

CONTRIBUTING.md

CONTRIBUTING.md

Dockerfile

Dockerfile

Dockerfile.release

Dockerfile.release

LICENSE

LICENSE

Makefile

Makefile

README.md

README.md

REVISIONS.md

REVISIONS.md

docker-compose.cluster.yaml

docker-compose.cluster.yaml

docker-compose.example.yaml

docker-compose.example.yaml

go.mod

go.mod

go.sum

go.sum

loomcycle-mcp.sh

loomcycle-mcp.sh

loomcycle.example.yaml

loomcycle.example.yaml

loomcycle.local-interactive.example.yaml

loomcycle.local-interactive.example.yaml

loomcycle.sh

loomcycle.sh

Repository files navigation

The agentic runtime, in a sidecar. loomcycle is one Go binary, ~50 MB. It runs alongside your application, not inside it. Your app calls loomcycle over HTTP, gRPC, MCP, the TypeScript adapter, or the Python adapter. The agent loop, multi-provider routing, memory and channel primitives, MCP server identity, OpenTelemetry traces, and multi-replica coordination all live in the binary. Your application stays in whatever language you wrote it in.

The shape that's different. Today's agentic-systems market gives you three options. One: embed a Python or TypeScript library inside your application process. Two: rent a managed cloud service tied to one vendor's IAM. Three: proxy your model calls through a gateway that doesn't actually run agents.

loomcycle is a fourth option. A lightweight self-hostable runtime that owns the loop and speaks every wire format your stack already uses.

What's shipped

Release Highlights

v0.4 → v0.26.x foundation Everything the runtime is built on, condensed. Seven inference modes: Anthropic, OpenAI, DeepSeek, Gemini, Ollama (cloud + local), plus the synthetic code-js provider and a mock provider. The hardened model → tool_use → tool_result loop. 19 built-in tools with Claude Code parity (Read, Write, Edit, Grep, Glob, NotebookEdit), plus HTTP, WebFetch, WebSearch, Bash, Agent, Skill, Memory, Channel, AgentDef, SkillDef, Evaluation, Interruption, Context. The content-addressed, runtime-mutable substrate (Agent / Skill / MCPServer / Schedule / Webhook / MemoryBackend / A2A defs). Vector Memory (sqlite-vec / pgvector) on a pluggable MemoryBackend, with a memory layer above. MCP on both sides. The LLM Gateway + OpenAI-compatible shims. A2A interop. Input webhooks. Ensemble-sync primitives (RFC S). OTEL + per-tenant fairness + Pause / Resume / Snapshot + multi-replica HA. Per-run named credentials + tool-use hooks. OSS multi-tenant authorization (RFC L, v0.17.0) across both the state and definition planes. The embedded React Web UI + the interactive terminal. TS + Python + n8n adapters. Homebrew + Docker distribution. Per-version detail: REVISIONS.md.

v0.27.0 Interactive runs survive leaving the terminal. Background-goroutine execution under context.WithoutCancel, re-attach via GET /v1/runs/{run_id}/stream (replay-from-?from_seq + live-tail). Context op=self reports the resolved provider + model.

v0.28.0 Per-agent LLM sampling (temperature / top_p / top_k / penalties / seed / stop, set via yaml or AgentDef overlay or per-run). And pause cooperative quiesce: the loop parks at an iteration boundary and Pause() waits for in-flight runs, so a mid-run snapshot is reliable.

v0.29.0 Web UI + operability. Agent-editor sampling controls + a collapsible advanced JSON/YAML overlay, terminal message-echo + a context-size gauge, and soft reclaim of a retired agent name (no new runtime primitives).

v0.30.0 Cross-instance resume of a snapshotted mid-run (RFC X Phase 2). A paused run is re-dispatched by reconstructing its loop from the transcript, fired after a snapshot restore and at boot (crash recovery, cluster-gated).

v0.31.0 Park + resume a fan-out parent blocked in Agent.parallel_spawn (RFC X Phase 3). Pause-watcher + a no-schema-change spawn ledger, gated behind LOOMCYCLE_RESUME_FANOUT.

v0.32.0 Context-compaction subsystem. Replace older turns with a summary + keep-last-N verbatim (clean user-turn boundary, non-destructive). Manual / auto / self triggers and a per-agent compaction block that flows down the spawn tree.

v0.33.0 External fan-out and the run-mutation surface on every transport. POST /v1/runs:batch, a spawn_runs MCP tool (≤32 server-concurrent), a SpawnRunBatch RPC. compact_run / CompactRun. Per-run sampling + compaction on MCP/gRPC. @loomcycle/client 0.33.0.

v0.34.0 Context-transform plugins (RFC Z Phase 1a, with the redact outbound-secret-scrub plugin), an exp7 self-review hardening pass, and a cross-provider thinking-model fallback downgrade (reasoner → chat).

v0.34.1 Hardening + branding (no new features). A central tenant-scoping store accessor closing three live cross-tenant read gaps (security review S2), plus the new loomcycle brand logo and favicon in the Web UI.

v0.34.2 Web UI design system + theming. A tokenized --lc-* design system (spacing / type / radius / shadow / fonts + semantic colors), light + dark themes (OS default + a persistent topbar toggle), bundled brand fonts (Outfit / Inter / JetBrains Mono), and the loom-wood #56c596 accent. Plus a loop fix (interactive runs unbounded by default; no more stop-at-16) and a -race test de-flake.

v0.34.3 Patch. Context op=self reports a fresh context footprint right after a compaction. It had kept showing the stale pre-compaction size (e.g. 164k / 82%) for one turn even though the wire request had already shrunk. The loop now refreshes lastCtxTokens at every compaction site.

v0.34.4 Patch. Interactive-terminal UX + local-model fixes: a collapsible interactive-sessions switcher on the run page (and interactive tags on the runs page), a flashing waiting indicator in the terminal, the Ollama context gauge backed by num_ctx, generous ollama-local timeouts (300s), relative sandbox paths anchored to the root (not the process cwd), and the static agent base re-surfaced in the Library when no dynamic version is active.

v0.34.5 Patch. Ollama now reports the model's actual loaded context window (read from /api/ps at the stream's done frame) instead of only a pinned num_ctx — so the gauge is truthful for local models loaded at the server's OLLAMA_CONTEXT_LENGTH; plus docs (the architecture diagram + ARCHITECTURE.md show the context-transform plugin layer; a README v1.0 voice refresh).

v0.35.0 Model aliases in tier candidates. A models: alias (e.g. local-gemma) now resolves anywhere a tier candidate is accepted — per-agent models:, user_tiers, and the library tiers: — not only in an agent pin, closing the "pin expands aliases but tier candidates don't" 503. A candidate can be written as a bare alias string (- local-gemma); config-load validation and the Web UI Library editor know aliases too.

v0.36.0 Jailed agents can see their sandbox. The Read/Write/Edit/Bash path docs now instruct relative paths (they wrongly said "Absolute file path," so agents passed host paths that resolve outside the jail), and Context op=self reports the sandbox roots (read_root/write_root/bash_cwd) + the effective host allowlist. Plus a collapsible left column on the run page so the live terminal can use the full width.

v0.37.0 Slow-local-model robustness. Two loop fixes that keep an interactive run on a slow local model alive for hours: a run-lifetime heartbeat (a long prefill / retry no longer gets reaped as a crashed run) and a compaction window cap (auto-compaction always fits the model's window instead of "succeeding" yet still overflowing). Plus an aliases-first loomcycle.example.yaml, a "Local models (Ollama)" config guide + a loomcycle.local-interactive.example.yaml. Validated by a 133-min standalone local run.

v1.0.0 🌳 1.0 — feature-complete, hardened, distribution-ready. The milestone the roadmap pointed at: no new primitives, the culmination of the v0.8→v0.37 primitive + hardening line. Apache-2.0, wired to Homebrew / multi-arch Docker / the Claude Code plugin. Same codebase as v0.37.0, tagged as the stable 1.0.

Full per-version log: REVISIONS.md.

Two postures, one binary

Same Go binary, same config schema. Operator flips a few env vars to pick the posture.

Posture Configuration shape Use case

True managed sandbox LOOMCYCLE_BASH_ENABLED=0, LOOMCYCLE_READ_ROOT / LOOMCYCLE_WRITE_ROOT unset, LOOMCYCLE_HTTP_HOST_ALLOWLIST empty, LOOMCYCLE_HTTP_CALLER_AUTHORITATIVE=1. Every tool default-deny; agents can only reach what the caller's per-request allowed_hosts says. Shared-server deployments processing untrusted prompts. The runtime survives contact with adversarial input.

Agentic dev environment Bash enabled, filesystem roots set to your workspace, broad allowed_hosts, optional local Ollama for offline work. Local development. Internal trusted operators. Single-user research workstation.

The trust boundary is operator / caller. The operator config is the floor; callers can narrow per-request but never widen. The bearer token (LOOMCYCLE_AUTH_TOKEN) is the authority. Treat anyone with the token as fully trusted to drive the runtime. For true isolation in the sandbox posture, run loomcycle inside a container or VM. Bash is restricted (cwd, env scrub, output bounds, timeouts) but it is not a kernel-level sandbox.

Install

Pick the path that fits. All four ship the same single static binary plus the v0.11.1 init / doctor first-run flow. Context.help installation covers each in detail.

Homebrew (macOS + Linux)

brew install denn-gubsky/loomcycle/loomcycle

Docker (v0.11.2+; pull works on amd64 + arm64 including Apple Silicon)

docker pull denngubsky/loomcycle:latest

go install from source (skips Web UI embedding — for dev only)

go install github.com/denn-gubsky/loomcycle/cmd/loomcycle@latest

Direct tarball (one of darwin-arm64 / darwin-amd64 / linux-arm64 / linux-amd64)

curl -L https://github.com/denn-gubsky/loomcycle/releases/latest/download/loomcycle-darwin-arm64.tar.gz | tar xz

Quick start (seconds, authenticated)

loomcycle init --with-token # writes config + mints a token to ~/.config/loomcycle/auth.env (0600) export ANTHROPIC_API_KEY=sk-... # (or OPENAI_API_KEY / DEEPSEEK_API_KEY) — at least one provider key loomcycle doctor # verify env + keys + storage + the just-minted token loomcycle # starts on 127.0.0.1:8787 (auto-loads auth.env — no shell-rc edit)

init --with-token prints the Web UI URL (http://127.0.0.1:8787/ui). Open it, then paste the token from ~/.config/loomcycle/auth.env at the login prompt. (The token is kept in the 0600 file and never embedded in a URL. A ?token= link would leak the bearer into browser history and into any fronting proxy's logs.) loomcycle and loomcycle doctor both auto-load auth.env from the config dir; a real export LOOMCYCLE_AUTH_TOKEN=… always overrides it.

Bootstrap tiers

Pick the tier that fits. Each is a superset of the one above. Auth is enforced only once something is configured, so Tier 1 needs no token at all.

Tier 1: zero-config dev (open mode, localhost)

No token, no flags. Fastest way to kick the tires on 127.0.0.1.

loomcycle init # config only — no secret written export ANTHROPIC_API_KEY=sk-... loomcycle # open mode: /v1/* + /ui pass through unauthenticated (logs a warning) open http://127.0.0.1:8787/ui

With no LOOMCYCLE_AUTH_TOKEN and no mi

[truncated for AI cost control]