Reference

Connect your agent

How an agent gets governed: Lodestar OSS wraps it in your environment and ships the recorded log to Machinaut. There are no per-agent adapters — “supported” means an agent fits one of Lodestar's integration paths. Claude Code is the path we've run end-to-end; every other agent is named honestly by tier.

You instrument the agent with Lodestar in your environment, then ship its session to Machinaut. Machinaut never runs the agent.

This is the practical companion to the govern loop. Everything on this page runs in your environment against Lodestar OSS (the data plane). Machinaut's only job is to receive what you ship — see the ingest contract.

Claude Code is the verified reference — the rest are tiered, not endorsed

Only Claude Code has been run end-to-end into the control plane, so it's the one recipe shown copy-paste-complete below. Every other agent is placed in a tier by whether its native tools can be disabled — the line between enforceable and bypassable governance — and named without implying governance we can't hold. These tools move fast; the matrix below is current as of 2026-06-29.

Before you start

Whichever path you take, you need two things from Machinaut:

An API token. Sign in to the console and mint one (POST /v1/tokens under the hood) — a project-scoped or tenant-scoped mk_… key, shown once. This is the LODESTAR_SHIP_TOKEN your shipper authenticates with.
Your ingest endpoint. The base URL of your Machinaut control plane (e.g. https://console.machinaut.ai). Pass it to the shipper as --endpoint; the CLI appends /v1/events itself — never include the path.

The four ways in

Lodestar wraps an agent one of four ways. Pick by how your agent runs; each ends by shipping a session to Machinaut.

Path	When	What it is
① MCP proxy	The dominant path	An off-the-shelf coding agent that speaks MCP. Point it at the governed proxy and disable its native tools — every action then flows through Lodestar.
② guard.wrap()	Your own TS loop	You run your own agent loop in TypeScript. Wrap it so every `ctx.callTool` routes through the kernel.
③ Runtime gate	Python frameworks · experimental	LangGraph, CrewAI, AutoGen, OpenHands. A native runtime hook spawns a gate that every tool call routes through.
④ No agent yet	Seed a sample	Nothing wired up? Load a synthetic-but-real chain so the explorer lights up while you set the real thing up.

Path ①: MCP proxy — the Claude Code recipe

The dominant path for off-the-shelf coding agents. The Lodestar guard runs as an MCP proxy in front of your real MCP servers; the agent talks to the proxy, the proxy records and gates every call, then forwards it downstream. The whole trick is to leave the agent no other way to act.

Governance holds only if native tools can be disabled

The proxy governs only the calls that route through it. If the agent keeps its own edit, read, shell, or web tools, it can act without the proxy ever seeing it — the chain silently misses those steps. Reads bypass just like edits do, so denying only writes still leaves the chain missing whatever the agent read or searched natively. An agent whose native tools can't be disabled is best-effort, not enforceable — see the tiers below.

The recipe is four files, then ship. Verified against the Lodestar v0.4.x CLI with Claude Code as the client.

1 · proxy.config.jsonjson

{
  "project_id": "my-agent",
  "actor_id": "agent:claude-code",
  "session_id": "auto",
  "log_root": ".lodestar/events",
  "default_scope": { "level": "project", "identifier": "my-agent" },
  "default_sensitivity": "internal",
  "auto_approve_ceiling": 3,
  "downstream_servers": [
    {
      "name": "fs",
      "command": "bunx",
      "args": ["@modelcontextprotocol/server-filesystem", "/abs/path/to/workspace"]
    }
  ]
}

Declares your downstream MCP servers and per-tool policy. Swap the workspace path and add the servers your agent uses. auto_approve_ceiling is the trust level below which actions run without a hold.

2 · .mcp.json — point Claude Code at the proxyjson

{
  "mcpServers": {
    "lodestar": {
      "command": "lodestar",
      "args": ["guard", "mcp-proxy", "--config", "proxy.config.json"]
    }
  }
}

The proxy advertises tools under the server name lodestar, so Claude Code sees them as mcp__lodestar__*.

3 · settings.json — the one thing that mattersjson

{
  "permissions": {
    "deny": [
      "Edit", "Write", "MultiEdit", "NotebookEdit", "Bash",
      "Read", "Glob", "Grep", "LS", "WebFetch", "WebSearch"
    ],
    "allow": ["mcp__lodestar__*"]
  }
}

Deny every native tool that touches the workspace, shell, or web, and allow only the proxy's mcp__lodestar__* tools — so the governed path is the agent's only path.

4 · launchbash

claude \
  --mcp-config .mcp.json --strict-mcp-config \
  --settings settings.json

--strict-mcp-config ignores any global or project MCP servers you already have, so the proxy is the only MCP route (without it, --mcp-config is additive, and a pre-existing server is an ungoverned bypass). The proxy prints its session id to stderr at startup ([mcp-proxy] session …).

Then ship the session the proxy printed. That's the full loop for the reference agent.

Which agents fit the proxy

The MCP-proxy path is tiered by one test: can the agent's native tools be turned off? Only the clean-fit tier gives you enforceable governance; the rest are honest about where they leak.

Clean fit

Enforceable

Native edit / shell / web tools can be disabled, so every action is forced through the governed proxy. Governance is enforceable.

Claude CodeVerified: The verified reference — run end-to-end into the control plane. Deny native tools and allow only mcp__lodestar__* in settings.json (launch with --strict-mcp-config).
Gemini CLI: Restrict built-ins via the tools.core allowlist so only the proxy's MCP tools are exposed.
Goose: Disable the built-in developer extension so edits and shell route through the MCP proxy.
Qwen Code: Gemini-CLI fork — same coreTools allowlist restricts native tools to the proxy.
Zed: Define a custom Agent Profile that omits the native edit / terminal tools.
Continue: Agent mode with native edit / terminal excluded from the permissions set.
Amp: amp.tools.disable: ["builtin:*"] drops the native tools, leaving only MCP.

Popular, caveated

Gated, not removed

The MCP add works, but native edits can be gated — not removed. Governed actions are recorded; native edits can still bypass the proxy.

Codex CLI: MCP add works, but apply_patch can't be removed (OpenAI Codex #6049). Run the sandbox read-only so native edits are gated, not gone.
Google Antigravity: Gates native tools but offers no true MCP-only mode — governed actions are recorded; native edits can still slip past.
Amazon Q CLI: Speaks MCP, but native-tool disable is unverified — treat as caveated until confirmed.

Best-effort

Bypassable

Real MCP clients, but native tools can't be disabled — so governance is best-effort (the proxy is bypassable).

Cursor: Real MCP client; native edit / terminal tools can't be disabled → bypassable.
Windsurf: Real MCP client; native tools can't be disabled → bypassable.
Cline: Real MCP client; native tools can't be disabled → bypassable.
Roo Code: Cline-family; native tools can't be disabled → bypassable.
Kilo Code: Cline-family; native tools can't be disabled → bypassable.

Doesn't fit the proxy

Different path, or none

Doesn't fit the MCP-proxy path. Listed so you know where they stand — some take a different path, some take none.

OpenHands: Python framework → fits Path ③ (runtime gate), not the MCP proxy.
Aider: Not an MCP client → none of the three paths apply.
OpenClaw: Personal-assistant gateway. Can act as an MCP server, but its native tools aren't restrictable — not a governable coding CLI.
Hermes Agent: Personal-assistant gateway — same as OpenClaw: not a restrictable coding CLI.

Path ②: guard.wrap() — your own TS loop

Running your own agent loop in TypeScript? Wrap it with the Lodestar trust layer — every ctx.callTool routes through the Action Kernel and Cognitive Core, producing the same event log the other paths ship. Register your tool adapters inside the loop; wrap() handles the governance, and the returned session_id is what you ship.

instrument your loopts

import { wrap, autoApprovePolicy, alwaysHoldsChecker } from "@qmilab/lodestar-guard"

const run = await wrap(myAgentLoop)({
  project_id: "my-agent",
  actor_id: "agent:dev",
  default_scope: { level: "project", identifier: "my-agent" },
  default_sensitivity: "internal",
  policy_gate: autoApprovePolicy({ auto_approve_up_to: 2, approver_id: "policy" }),
  precondition_checker: alwaysHoldsChecker,
})

console.log(run.session_id) // → ship this

Path ③: Runtime gate — Python frameworks

Experimental For Python frameworks — LangGraph, CrewAI, AutoGen, OpenHands. The native runtime hook (e.g. the Python lodestar-langgraph package) spawns the gate and speaks JSON-RPC to it; every native tool call routes through the Action Kernel. Your framework hook is the parent process — it launches the gate and talks to it over stdin/stdout, and the gate prints its session id to stderr at startup.

start the gatebash

lodestar runtime gate --config gate.config.json

Path ④: No agent yet — seed a sample

Want to see a chain before you instrument anything? The fastest path is one click: Explore a sample project in the console seeds a labelled sample into your own tenant — a real chain, a held approval, and an audit trail — via POST /v1/demo/seed (see the API reference). The sample authors a plausible Lodestar-OSS chain; Machinaut only hosts, indexes, and relays it.

From a machinaut checkout you can do the same from the shell. It POSTs a synthetic, schema-valid chain — observations → claims → evidence → belief → decision → an approved L4 action — straight to /v1/events, so it needs no separate ship step (and it's idempotent — re-running is a no-op).

seed a demo sessionbash

MACHINAUT_URL=https://console.machinaut.ai MACHINAUT_KEY=mk_live_… \
  bun scripts/seed-demo.ts

MACHINAUT_URL is the base URL; MACHINAUT_KEY is the same mk_… token minted above.

Ship the session

Paths ①–③ finish the same way: ship the recorded session to your ingest endpoint. The token rides an environment variable — the shipper refuses credentials on the command line, so a secret never lands in argv or your shell history. --endpoint is the base URL; the CLI appends /v1/events.

ship to Machinautbash

LODESTAR_SHIP_TOKEN=mk_live_… \
  lodestar ship <session-id> --endpoint https://console.machinaut.ai

Replace <session-id> with the id the proxy, gate, or wrap() printed. Re-shipping a session that grew is free — the ingest contract dedupes on (project_id, session_id, seq).

What ships, and what happens next

The shipper redacts anything above your sensitivity ceiling before the bytes leave your environment, keeping only a hash as a commitment. Once ingested, the session is a hosted, searchable, shareable chain — and if it carries a held action, it lands in the approval inbox. Read the wire format in the ingest contract and the hold transport in the approval relay contract.