Cross-checked every runtime list against the canonical AllRuntimes
allowlist in workspace-server/internal/handlers/admin_workspace_images.go
(claude-code, langgraph, crewai, autogen, deepagents, hermes, gemini-cli,
openclaw). Lists were drifting toward an old 6-runtime snapshot, missing
hermes + gemini-cli; one file referenced a non-existent NemoClaw branch
plus NVIDIA T4 hardware that has no source presence anywhere in the
monorepo (verified: no `feat/nemoclaw-t4-docker` branch, no `nemoclaw`
references outside docs).
Files changed:
content/docs/agent-runtime/workspace-runtime.md
- Before: "Current `main` ships six adapters" listing langgraph,
deepagents, claude-code, crewai, autogen, openclaw + a
"Branch-level experiments such as NemoClaw" sentence.
- After: "Current `main` ships eight adapters" — added hermes +
gemini-cli; removed NemoClaw line; pointed readers at AllRuntimes
as the source of truth and external-workspace path for BYO.
content/docs/architecture/molecule-technical-doc.md (two locations)
- Before (runtime table ~line 575): 6 rows + "Branch-level WIP:
NemoClaw (NVIDIA T4 + Docker socket) on feat/nemoclaw-t4-docker".
- After: 8 rows including Hermes + Gemini CLI; NemoClaw line
deleted; AllRuntimes pointer added.
- Before (Branch-Level Work table ~line 981): row
"feat/nemoclaw-t4-docker | NemoClaw adapter (NVIDIA T4 support) | WIP".
- After: row removed (the branch does not exist).
content/docs/architecture/overview.md
- Before: "Supports LangGraph, Claude Code, OpenClaw, DeepAgents,
CrewAI, AutoGen."
- After: "Supports Claude Code, LangGraph, CrewAI, AutoGen, DeepAgents,
Hermes, Gemini CLI, and OpenClaw."
content/docs/glossary.md
- Before: runtime defined as "one of langgraph, claude-code, openclaw,
crewai, autogen, deepagents, hermes" (7, missing gemini-cli).
- After: full 8-entry list ordered to match AllRuntimes.
Out-of-scope sweep results (no changes needed):
- "NeMo Guardrails" — zero references in molecule-docs (the
"guardrails" word elsewhere refers to generic plugin/role guardrails,
not the NVIDIA NeMo Guardrails product). Nothing to remove.
- "Nemotron" — only present in the monorepo as a NIM model alias
inside a model-dispatcher test; no first-class model claim in docs.
- Model lists in docs match workspace/agent.py (Anthropic, OpenAI,
Gemini, MiniMax, DeepSeek, Moonshot, local Ollama/vLLM); no
Nemotron claims to remove.
- Observability sinks (OpenTelemetry, Langfuse, Sentry, Prometheus
references) match implementation; no NeMo Guardrails sink claimed.
- index.mdx, concepts.mdx, architecture.mdx already list the full 8
runtimes; no edit needed there.
Verified via `npm run build` — all 111 static pages regenerate clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds a "Runtime Distribution" section to agent-runtime/workspace-runtime.md
explaining that the PyPI wheel is the canonical artifact and the
molecule-ai-workspace-runtime git mirror may lag behind (or be skipped
entirely on transient publish failures).
Originally drafted as a README change to the mirror itself
(molecule-ai-workspace-runtime#62), but mirror-guard correctly blocks
direct PRs there. The docs surface is the right home for "how the
publish pipeline works" — it's discoverable from the agent-runtime
section and lives next to the existing Boot-Smoke Contract section
that gates publish.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The "Architecture" diagram and section 5 ("Cloudflare: staging
subdomain") both implied that `*.staging.moleculesai.app` is a wildcard
DNS record. It is not. The control plane writes a per-tenant CNAME at
provision time (see `internal/provisioner/ec2.go` ->
`Tunnel.CreateTunnelDNS`), and unknown slugs correctly return NXDOMAIN.
This rewrite:
- Replaces `*.staging.moleculesai.app` / `*.moleculesai.app` in the
ASCII diagram with `<slug>.<env-domain>` plus a "no wildcard" note.
- Renames section 5 to "Cloudflare: per-tenant CNAMEs (no wildcard)"
and explains that NXDOMAIN on unknown slugs is correct, that
`getaddrinfo ENOTFOUND` in tests means the slug is unprovisioned
(not an infra bug), and that the same model applies to both
staging and production.
Older `claude mcp add ... -- env VAR=val molecule-mcp` snippets land as
`command: "env"` with positional args, which is fragile across 2.1.x
patch builds and unfamiliar to anyone reading `~/.claude.json` directly.
The post-2.1 CLI also rejects the form without a `--` between flags and
command (external feedback in #112).
Replace both snippets (basic install + identity-with-skills) with:
1. Modern CLI form using `-e KEY=VAL` and an explicit `--`.
2. Parallel `~/.claude.json` JSON shape under top-level `mcpServers` for
user scope (or `.mcp.json` in project root for project scope), so
users on any 2.1.x patch level have an authoritative reference if
the CLI form misbehaves.
Add a Troubleshooting entry for the two common 2.1+ CLI rejections, and
fix the broken `[Install](#install)` cross-link in the dev-channels
section to point at `[Step 2](#claude-code)`.
ClosesMolecule-AI/docs#112.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds a per-attribute reference table for the <channel> tag (push
path) and the equivalent JSON shape (poll path) so the agent — and
operators reading the docs — know what metadata to expect for every
inbound message.
Covers the new peer_name, peer_role, agent_card_url fields landing
with the wheel-side enrichment in molecule-core#2471, including the
registry-lookup graceful-degrade rule (lookup failure → attrs
absent, push still delivers) and the deterministic agent_card_url
construction (present even on registry outage).
Includes a worked example of a peer_agent push so a reader can copy
the wire shape into their own host bridge if they need to validate
what they're seeing.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Claude Code 2.1.x changed the flag's signature to require an allowlist
of tagged entries — `server:<name>` for manually-configured MCP
servers, `plugin:<name>@<marketplace>` for plugin channels. The
previous bare-switch form was rejected with `argument missing`, and
an untagged value returns `entries must be tagged`.
Doc updates:
- Replace bare-flag references with tagged form throughout (env-var
table, push-path narrative, capability matrix)
- Add a worked example showing `claude --dangerously-load-development-
channels server:molecule` and the `Listening for channel messages
from: server:molecule` confirmation header so operators have a
visible signal that push is live
- Note the multi-server form (space-separated tagged entries)
- Three new troubleshooting entries:
* `argument missing` → forgot the value
* `entries must be tagged` → forgot the tag
* `Control request timeout: initialize` → embedded the flag in an
SDK options bundle as `{flag: None}` instead of `{flag:
"server:molecule"}` — covers the workspace-side regression we
caught live on dd40faf8 on 2026-05-01
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Bare <ws-id> in headings emitted a `raw` HAST node that the renderer
couldn't handle ("Cannot handle unknown node `raw`"). Wrapping in
backticks renders as inline code instead of being parsed as JSX/HTML.
Verified locally with `npm run build` (106/106 static pages green).
Two errors caught by the docs build CI on PR #98:
1. external-agents.mdx line 15 had `<1 min.` — the literal `<` made the
MDX parser try to read it as a JSX tag opener. Replaced with prose
"under a minute" — equivalent meaning, no escape gymnastics.
2. claude-code-channel-plugin.md used `<Callout type="info">` JSX, but
the rest of /content/docs/guides/ is plain .md (no JSX). The .md
loader can't resolve the Callout component → "Cannot handle unknown
node `raw`". Replaced with a `> **Note:**` blockquote — same visual
hierarchy, plain markdown.
Verified locally that the offending characters are gone; build CI on
push will re-run and should now pass.
Adds /docs/guides/claude-code-channel-plugin.md — the canonical guide
for connecting a Claude Code session as a Molecule external workspace
via the new Molecule-AI/molecule-mcp-claude-channel plugin. Polling-
based; no tunnel required.
Cross-references added:
- content/docs/external-agents.mdx — new "Pick the right path" table
at top, distinguishing Claude Code (channel plugin) from generic
HTTP-speaking agents (this page) at first glance.
- content/docs/guides/external-workspace-quickstart.md — short
redirect callout near the top so laptop-Claude-Code users are
routed to the channel plugin guide instead of the tunnel-required
quickstart.
Per molecule-core's #2060 content-routing policy, public-facing docs
live in this repo. The plugin source + README live separately at
github.com/Molecule-AI/molecule-mcp-claude-channel; this guide
duplicates the operator-facing setup steps and adds Molecule-specific
context (how to get workspace_id + token from canvas, how /activity
shows up, troubleshooting against /activity endpoint shape).
Mirrors molecule-core feat/universal-push-via-instructions: documents
the universal poll path (instructions field → every MCP client) plus
the optional push path (notifications/claude/channel for Claude Code
with the dev-channels flag or a future allowlist entry).
Honesty pass on the prior text: previous version claimed push works
"automatically" and "there is no config flag to toggle." That was
true for the wire shape but false for live UX — standard `claude`
launches without --dangerously-load-development-channels silently
drop the notification, and non-Claude clients ignore the Claude-
namespaced method entirely. New text spells out exactly which clients
get push, which get poll, and the per-client capability matrix.
Adds MOLECULE_MCP_POLL_TIMEOUT_SECS to the env-var table — the new
operator knob landed in the wheel.
Successor to #44/#49 (which closed without the flag caveat).
Two errors in the merged caveat (#107):
1. Claimed the stub RequestContext "carries an empty user message"
— actually carries "smoke test" text (smoke_mode.py:76 calls
`new_text_message("smoke test")`, with the explicit comment
that it's "enough that extract_message_text(context) returns
non-empty input"). Adapter authors gating smoke-mode behavior
on extract_message_text(ctx) == "" would have a logic that
never fires.
2. Described only the timeout-pass path. The harness also returns
0 on ANY non-import exception (smoke_mode.py:135-143) — the
bare `except Exception` block treats RuntimeError, auth errors,
validation errors etc. as "downstream of the import gate" and
exits clean. Spelling out all three pass cases (clean return,
timeout, non-import exception) is the honest description.
Caught while re-reading smoke_mode.py to verify claims for a
review pass — found I had asserted both behaviors from memory
without checking, exactly the failure mode my e2e-test memory
just got a worked-example update about.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
A green gate means imports are healthy enough that
executor.execute() reaches its body. It does NOT prove that
execute() produces the right output: adapters with real I/O
inside execute() (subprocess to a gateway, httpx call upstream)
time out under the 5s harness window, and the gate treats a clean
timeout as success.
Surfaced while running publish-image across all 8 templates: the
openclaw smoke "passed" with timing-out behavior in execute()
because OpenClawA2AExecutor proxies to a subprocess that doesn't
exist in the smoke env. Reading the green check, future operators
might over-trust it as a runtime-correctness signal — it isn't.
Add a "What the gate does NOT prove" subsection so readers don't
mistake the import-regression coverage for an integration test.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The publish-image boot-smoke gate (molecule-core#2275) invokes the
runtime with MOLECULE_SMOKE_MODE=1 + stub creds to catch lazy
imports inside executor.execute(). Adapters whose setup() does
real I/O (subprocess spawn, network calls, uid-sensitive writes)
need to opt out of that I/O when MOLECULE_SMOKE_MODE=1, otherwise
the gate fails before reaching the runtime's smoke short-circuit.
This documents:
- the contract (one-line opt-out for Python adapter.setup() and
shell entrypoints that wrap molecule-runtime)
- which boot stages the gate exercises
- the stub env the harness sets so adapters can reason about what
they can rely on under smoke mode
Surfaced when running publish-image across all 8 workspace
templates: openclaw and hermes hit the contract gap because both
spawn real gateway subprocesses in setup; six others passed
without any contract awareness because their setup is light.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Brings the docs site in visual parity with moleculesai.app so docs,
marketing, and the canvas read as one product. Five focused changes
inside the existing fumadocs shell — no MDX or content touched, no
runtime/build dep changes:
- global.css: override fumadocs @theme tokens with the warm-paper
palette (#fafaf7 bg, #15181c ink, #3b5bdb governance blue,
#efece4 muted, #e6e2d8 border). Dark mode keeps fumadocs' neutral
defaults so dark-pref readers still get a readable docs site.
- layout.tsx: swap Inter → Geist (sans) + JetBrains Mono (code),
matching the landing's font stack. Wired through @theme so
Tailwind's font-sans / font-mono utilities pick them up.
- layout.config.tsx: brand the topbar — inline Molecule logo SVG +
"Molecule AI · DOCS" lockup, plus three external links to the rest
of the surface (Platform → app, Marketplace → market, Landing →
www) and the org GitHub. Mirrors the landing's collapsed nav.
- (home)/page.tsx: replace the stock fumadocs landing with a
hero-style page matching the landing — statusbar strip, "Phase 35
Marketplace public beta" eyebrow, the same shimmering h1 copy,
three quick-start lane cards (Build a workspace / Run an
organisation / Publish to the Marketplace) pointing into the docs
tree.
Build is clean (106 static pages still generate). Existing /docs/*
pages inherit the new tokens via fumadocs' DocsLayout, so the entire
site shifts to the warm-paper aesthetic without touching MDX.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Follow-up C to molecule-core#2449 + #2451 (a2a-client) +
molecule-mcp-claude-channel#22 (channel bridge):
- runtime-mcp.mdx Troubleshooting: new section explaining the 410
startup-time error from `get_workspace_info`, contrasting it with
the heartbeat-401 escalation (which is the steady-state cure), and
documenting the `?include_removed=true` opt-in for audit tooling.
- external-agents.mdx Lifecycle: expanded the `removed` status with
a per-caller behavior table so operators know exactly what each
surface (wheel heartbeat, MCP tool, channel bridge, raw curl) looks
like for a removed workspace.
Both pages link back to the underlying PR so the audit trail is
single-click navigable from the docs.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds a "MCP spec compliance" subsection to runtime-mcp.mdx that:
- Lists which MCP methods the wheel implements + how
- Notes the wheel speaks protocol version 2024-11-05 with only the
`tools` capability (no streaming, no logging)
- Clarifies that notifications/claude/channel is the only non-spec
method emitted, and that clients which don't handle it discard
per JSON-RPC semantics
- States explicitly that any spec-compliant MCP client can drive
the wheel (Claude Code, Cursor, Cline, OpenCode, hermes-agent,
or anything else that opens MCP stdio)
This is the deliverable for verifying cross-client compatibility.
The wheel uses no client-specific behavior, so the verification
reduces to "does your client speak MCP 2024-11-05?" — which all
the listed clients do.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two additions to the universal MCP runtime page:
1. New "Push-UX for notification-capable hosts" subsection explains
that the wheel emits notifications/claude/channel on every new
inbound message — Claude Code (and any compliant client) gets
push-style interrupts, poll-only runtimes silently fall back to
wait_for_message / inbox_peek. Same wheel for both, no config flag.
2. Three new troubleshooting entries from real install pitfalls:
- Tools 401 after working: workspace was deleted from the canvas
(token revoked); regenerate from Tokens tab
- claude mcp list shows new config but /mcp reconnect still uses
cache — must fully exit + relaunch the runtime
- command not found from inside runtime: PATH differs from
interactive shell (esp. macOS GUI-launched apps); use the
absolute path from `which molecule-mcp`
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds an "Optional — declare your identity & capabilities" section to
the Bring Your Own Runtime page covering the three new env vars
landing in molecule-core PR #2428:
* MOLECULE_AGENT_NAME — display name on canvas card
* MOLECULE_AGENT_DESCRIPTION — one-liner in Details/Skills tabs
* MOLECULE_AGENT_SKILLS — comma-separated skills
Includes a worked example for Claude Code's add command and explains
the two surfaces these populate (canvas Skills tab, peer agents'
list_peers output) so readers understand why declaring skills matters
for routing.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The universal molecule-mcp wheel is the recommended path for any
MCP-aware runtime — Claude Code, hermes-agent, OpenCode, Cursor, Cline,
custom MCP clients — to join the canvas as a first-class external
workspace. Until now this path had no docs page; users either inferred
it from internal PRs or got pointed at external-agents.mdx (the manual
HTTP+heartbeat path that pre-dates the wheel).
New runtime-mcp.mdx covers:
* Single install (pip install --user molecule-ai-workspace-runtime)
* Per-runtime config snippets (Claude Code, Hermes, generic JSON,
Cursor/Cline)
* Tool surface (delegate_task, wait_for_message, inbox_peek/pop,
send_message_to_user, commit_memory/recall_memory)
* Heartbeat/lifecycle behaviour and the new escalation message
landed in molecule-core PR #2425
* When to use this vs. the manual external-agents path
* Troubleshooting: stale MCP cache, 401 register failure, PATH issues
Cross-links:
* external-agents.mdx now leads with a Callout pointing MCP-runtime
users at the new page; keeps the manual path for non-MCP agents
* meta.json registers the new page under the main docs nav between
schedules and external-agents (related onboarding flow)
Build verified: `npm run build` generates 106 pages including the new
/docs/runtime-mcp.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two additive pages tied to the new Marketplace surfaces on the
landing page and molecule-app workspace UI:
- content/docs/marketplace.mdx — L1 plugins / L2 agents / L3 bundles
tier model, trust tiers (Verified / Partner / Community), install
flow, and workspace.yaml pin examples.
- content/docs/marketplace/creators.mdx — three-step (Build · List ·
Earn) builder workflow: SDK refs, Creator Portal submission, pricing
options, policy/safety terms, and maintenance.
Wired into meta.json under a new ---Marketplace--- section between
Troubleshooting and Security.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
