Marmot
Protocol
Development Kit
Documentation
Apps
Awesome
Releases
Community
GitHub
Donate
Contact
Protocol
Development Kit
Documentation
Apps
Awesome
Releases
Community
GitHub
Donate
Contact
  • Start here

    • Documentation
  • Integration guides

    • Native apps · MarmotKit
    • Rust application runtime
    • C and native hosts
    • Bots and agents
    • Terminal and scripts
    • TypeScript quickstart
    • TypeScript storage
    • TypeScript networking
  • Reference

    • MarmotKit distribution
    • MarmotKit API
    • C API
    • Architecture
    • Upgrade guide

Bots and agents

MDK 0.17.0View source on GitHub

This guide follows the latest stable release. Use the documentation at your installed version’s tag when working with an older release.

Marmot Integrations

Connectors that let you chat with an agent runtime you already run (Hermes, OpenClaw, Claude Code, Codex, OpenCode, Pi, or Goose) from White Noise, over end-to-end encrypted Marmot groups. Each connector runs next to the local wn-agent service on your Mac or Linux machine. Start with Get Started; the later sections explain topology, identities, and sharing for operators. To write your own client against wn-agent instead, such as a notifier bot, see Build your own client.

Contents

  • Get Started: White Noise + Agents
  • Optional latest release selection
  • Recommended chat setup
  • Connector capabilities
  • First-install verification
  • How The Connectors Fit Together
  • Default Install Topology
  • Identity Model
  • What Is Shared
  • What Is Separate
  • Allowlist Behavior
  • Sharing Options
  • Development Paths

Get Started: White Noise + Agents

You need:

  • White Noise on your phone, with your account npub available;
  • one supported agent runtime already installed, authenticated, and working on the same Mac or Linux machine where you will run the connector;
  • Linux x86_64, Linux arm64, macOS Apple Silicon, or macOS Intel.

For Claude Code, paste the copied White Noise installation prompt into Claude Code in a terminal on the computer where the connector will run. The Claude mobile app uses a separate cloud session; installation belongs on your Mac or Linux machine. Install and sign in to Claude Code first using its official setup guide, then check claude --version and an ordinary local conversation under the service user.

On your phone, check that White Noise's relay list contains wss://relay.eu.whitenoise.chat and wss://relay.us.whitenoise.chat for the default setup. Check the phone settings directly; the connector computer cannot confirm them. For a custom set, configure the connector to match it.

Choose the runtime you already use:

Runtime Connector style Best fit
Hermes Gateway plugin Rich chat history, reactions, media, and live previews
OpenClaw Channel plugin Gateway routing, history and media
Claude Code Terminal harness Repository and coding tasks through Claude Code
Codex Terminal harness Repository and coding tasks through Codex
OpenCode Terminal harness Repository and coding tasks through OpenCode
Pi Terminal harness Repository and coding tasks through Pi
Goose Terminal harness Repository and coding tasks through Goose
Your own client wn-agent only Notifier bots, scripts and custom runtimes (guide)

The guided installers prompt on the terminal for the White Noise account that may invite and message the agent. They install the selected WN Agent release, create an isolated White Noise identity for the selected connector, and start same-user services where supported. Download each installer with its adjacent checksum, verify it, and only then execute the local file:

Verified installer helper

Define this helper once, then choose a runtime below. It downloads the installer and its sibling checksum, verifies the bytes, and runs only the verified local file. The release publisher is the trust anchor; the checksum is not an independent endorsement. The helper runs the verified script with bash; do not double-click the downloaded .sh file. For a manual download, verify its matching checksum before running bash install-claude-marmot.sh.

For the documented release, use the pinned base_url below. Its installers and companion assets stay in the same cohort. Remove stale MARMOT_RELEASE_REPO, MARMOT_RELEASE_TAG, WN_AGENT_VERSION and WN_AGENT_SHA overrides for a default install; explicit overrides describe a custom deployment.

install_verified() (
  set -eu
  installer_url="$1"
  checksum_url="$2"
  shift 2
  case "$installer_url" in
    *[!a-zA-Z0-9:/._-]*) echo "error: invalid installer URL" >&2; exit 1 ;;
  esac
  if ! printf '%s\n' "$installer_url" | LC_ALL=C grep -Eq '^https://github[.]com/marmot-protocol/mdk/releases/download/wn-agent-v[0-9]+[.][0-9]+[.][0-9]+/install-((hermes|openclaw|claude|codex|opencode|pi|goose)-marmot|wn-agent)[.]sh$'; then
    echo "error: select a numeric WN Agent release before installing" >&2
    exit 1
  fi
  if [ "$checksum_url" != "$installer_url.sha256" ]; then
    echo "error: checksum must accompany the same release installer" >&2
    exit 1
  fi
  installer_script="${installer_url##*/}"
  tmpdir="$(mktemp -d)"
  trap 'rm -rf "$tmpdir"' 0 HUP INT TERM
  curl -fsSL --proto '=https' --proto-redir '=https' --connect-timeout 10 --max-time 180 "$installer_url" -o "$tmpdir/$installer_script"
  curl -fsSL --proto '=https' --proto-redir '=https' --connect-timeout 10 --max-time 180 "$checksum_url" -o "$tmpdir/$installer_script.sha256"
  if command -v shasum >/dev/null 2>&1; then
    (cd "$tmpdir" && shasum -a 256 -c "$installer_script.sha256")
  elif command -v sha256sum >/dev/null 2>&1; then
    (cd "$tmpdir" && sha256sum -c "$installer_script.sha256")
  else
    echo "error: need shasum or sha256sum to verify the installer" >&2
    exit 1
  fi
  bash "$tmpdir/$installer_script" "$@"
)
base_url="https://github.com/marmot-protocol/mdk/releases/download/wn-agent-v0.17.0"

Hermes

Hermes 0.19.0 or newer must already be installed and working.

If Hermes has multiple profiles or a custom home, read first install and profile selection before invoking the installer. Export the intended HERMES_HOME, and choose separate connector homes/sockets/service names for independent agents. The installer does not infer the intended profile from the installation prompt.

Run this example in the same shell where install_verified above was defined.

install_verified "$base_url/install-hermes-marmot.sh" \
  "$base_url/install-hermes-marmot.sh.sha256"

OpenClaw

OpenClaw 2026.10.10 or newer and Node 24.22.1+ (24.x) or 26.12.1+ must already be installed.

Run this example in the same shell where install_verified above was defined.

install_verified "$base_url/install-openclaw-marmot.sh" \
  "$base_url/install-openclaw-marmot.sh.sha256"

Claude Code

Claude Code 2.1.0 or newer must already be installed, authenticated, and runnable as claude on the connector computer. See the official setup guide if it is not ready.

Run this example in the same shell where install_verified above was defined.

install_verified "$base_url/install-claude-marmot.sh" \
  "$base_url/install-claude-marmot.sh.sha256"

Codex

Codex must already be installed, authenticated, and runnable as codex.

Run this example in the same shell where install_verified above was defined.

install_verified "$base_url/install-codex-marmot.sh" \
  "$base_url/install-codex-marmot.sh.sha256"

OpenCode

OpenCode 1.18.18 or newer must already be installed and runnable as opencode.

Run this example in the same shell where install_verified above was defined.

install_verified "$base_url/install-opencode-marmot.sh" \
  "$base_url/install-opencode-marmot.sh.sha256"

Pi

Pi must already be installed, authenticated, and runnable as pi.

Run this example in the same shell where install_verified above was defined.

install_verified "$base_url/install-pi-marmot.sh" \
  "$base_url/install-pi-marmot.sh.sha256"

Goose

Goose 1.53.0 or newer must already be installed, configured with a provider, and runnable as goose. The Goose harness supports the inherit and unrestricted execution profiles only.

Run this example in the same shell where install_verified above was defined.

install_verified "$base_url/install-goose-marmot.sh" \
  "$base_url/install-goose-marmot.sh.sha256"

wn-agent only (your own client)

For your own client against the control socket, such as a notifier bot, this installer installs and starts wn-agent alone, without a harness or plugin. --bootstrap creates the agent identity; --import-identity imports an existing key instead. The connector's identity must not also be signed in on another client. Continue with Build your own client.

install-wn-agent.sh is published from WN Agent 0.15.0 onward. If you pin 0.14.0 or earlier in base_url, run the installer from a clone of this repository instead. It downloads and verifies that release's wn-agent bundle the same way:

bash scripts/install-wn-agent.sh --bootstrap

Otherwise, run this example in the same shell where install_verified above was defined.

install_verified "$base_url/install-wn-agent.sh" \
  "$base_url/install-wn-agent.sh.sha256" --bootstrap

Finish In White Noise

Each installer records the new agent's npub and nprofile in the bootstrap.json path printed at completion. Display them with:

python3 -c 'import json,sys; d=json.load(open(sys.argv[1])); print(d["npub"]); print(d["nprofile"])' \
  "$HOME/.marmot-agents/codex/bootstrap.json"

Use hermes, openclaw, claude, codex, harnesses (OpenCode), pi, or goose in that path. The installers also show these values directly and render a terminal QR when qrencode is installed.

  1. Compare the entire agent npub displayed on your trusted computer with the account you add in White Noise. Check the account before accepting an agent-created invitation or sending a task. A name, emoji, group title, or public profile is not proof of identity.
  2. Give the verified account a local nickname, where your app supports it. The terminal installers do not publish a public agent profile. Suggested cues are 🧑‍💻 Codex, 🦀 Claude Code, 🥧 Pi, and 🛠️ OpenCode; different installations can have different private nicknames.
  3. Invite it from the account you authorized. Terminal task groups can use a normal group; ordinary messaging does not require an admin grant.
  4. Send a harmless test prompt with a fresh word you choose, asking the agent to echo that word without running tools or changing files. Check that the backend's reply contains that word and arrives in the same verified group; an older reply or a service-start acknowledgement does not prove this test succeeded.

For terminal harnesses (Claude Code, Codex, OpenCode, and Pi), first select a workspace with /<path> beneath your home directory. For Codex, choose a Git repository. A terminal harness /status response alone does not prove that its backend can answer a phone prompt. Hermes and OpenClaw use their own gateway workspace/session configuration instead of this terminal picker.

Connector files being installed is one milestone; a verified phone-to-backend conversation is another. Terminal automatic titles require an instruction plus matching group-profile-capable connector and harness releases. They are not enabled by the installation steps alone. Once that capability is available, you can grant the verified agent admin permission for title edits in a normal group. This also allows group and member changes. Direct messages do not provide the same editable group-title workflow. See the shared session workflow and onboarding design for the proposed defaults and their remaining dependencies.

Hermes and OpenClaw print one final gateway restart command because the installer does not restart an existing gateway. Claude Code, Codex, OpenCode, Pi, and Goose services are started by the default install. Their first group message can be /<path> to select a working directory under your home directory.

Repeatable Agent Or CI Setup

For repeatable CI, save the exact numeric release URL printed during a reviewed setup and set base_url to that saved URL instead of selecting a newer release again on every run. Set WN_AGENT_PINNED_BASE_URL in the CI environment to that reviewed exact URL; the example clears a previously resolved value if the pin is missing, so the installer helper refuses it before any download. Provide the authorized White Noise account explicitly. Terminal harnesses use the welcomer entry for both invitation and prompt authorization. OpenClaw keeps those boundaries separate: --allow-welcomer is invite admission only, and inbound sender authorization is a distinct senderPolicy / MARMOT_ALLOWED_USERS configuration.

Run this example in the same shell where install_verified above was defined.

OWNER_NPUB=npub1...
base_url="${WN_AGENT_PINNED_BASE_URL:-}"
install_verified "$base_url/install-codex-marmot.sh" \
  "$base_url/install-codex-marmot.sh.sha256" \
  --yes --allow-welcomer "$OWNER_NPUB"

Replace codex in the URL with claude, openclaw, opencode, pi, or goose. Hermes keeps invite acceptance and message-sender authorization explicit:

Run this example in the same shell where install_verified above was defined.

install_verified "$base_url/install-hermes-marmot.sh" \
  "$base_url/install-hermes-marmot.sh.sha256" \
  --yes --allow-welcomer "$OWNER_NPUB" --allow-user "$OWNER_NPUB"

Every installer verifies the downloaded binary and plugin assets against the checksums from the same immutable release. For independent verification of the installer itself, download its adjacent .sha256 asset before running it.

Use each connector's README for existing-identity imports, shared deployments, execution profiles, manual service control, and development workflows.

Optional latest release selection

The default commands above use the release documented by this checkout. To choose a newer release, first review its matching installation guide and compatibility notes in the release list. This optional lookup requires Python 3 with working TLS and GitHub API access; it accepts published numeric WN Agent tags, including pre-releases, and excludes drafts and suffixed tags. GitHub's repository-wide /releases/latest can select a different product. The lookup stops after 1,000 entries and clears base_url on failure. Fix API, network or certificate errors, or choose a numeric release explicitly. Installer and checksum verification remain required.

Run this optional lookup in the same shell as the helper, then use the selected runtime's install_verified command. Save the printed URL for repeatable installs.

if base_url="$(python3 - <<'RELEASE'
import json, re, urllib.request
candidates = []
for page in range(1, 11):
    url = f"https://api.github.com/repos/marmot-protocol/mdk/releases?per_page=100&page={page}"
    with urllib.request.urlopen(url, timeout=30) as response:
        releases = json.load(response)
    for release in releases:
        tag = release["tag_name"]
        match = re.fullmatch(r"wn-agent-v([0-9]+)\.([0-9]+)\.([0-9]+)", tag)
        if match and not release["draft"] and release["published_at"]:
            candidates.append((tuple(map(int, match.groups())), tag))
    if len(releases) < 100:
        break
else:
    raise SystemExit("Release listing exceeded 1000 entries; choose a reviewed tag explicitly")
if not candidates:
    raise SystemExit("No published WN Agent release found")
tag = max(candidates)[1]
print(f"https://github.com/marmot-protocol/mdk/releases/download/{tag}")
RELEASE
)" && test -n "$base_url"; then
  printf 'Selected WN Agent release: %s\n' "$base_url"
else
  base_url=""
  printf '%s\n' 'error: release lookup failed; installation is unavailable until resolved' >&2
fi

Recommended chat setup

For a personal agent chat, the recommended setup is a dedicated group/DM with the agent promoted to group admin so it can maintain a useful task title. The phone owner performs the promotion through White Noise's group management. Group admin carries real membership/profile authority; keep the human owner as an admin too. This is recommended for trusted agents, not an automatic grant in every shared group. Admin status does not authorize new senders or grant backend tools. Ordinary messages and reactions do not require admin status.

Before installation, settle the few choices that change the setup:

  • Which runtime/profile and existing account should this chat use? Default to the selected runtime's isolated connector identity; reuse an identity only when requested.
  • Which phone account may invite and prompt it, and which project directory should terminal-harness work start in?
  • Is this a trusted personal agent chat with admin/title management? Recommend yes; keep a shared group member-only unless its owner chooses otherwise.
  • Which files are needed, and is generated-file delivery supported/configured? Keep the selected runtime's existing permissions as the execution default.

Agent setup and chat policy is collected in the integration instructions. These instructions are not installed automatically; tools still need deployment configuration and the acceptance check below.

Check the tools before promising the experience

  • Hermes: marmot_group_profile updates a name/description as an admin; marmot_reaction adds/removes a message reaction. The optional presence policy and model-issued reactions need one consistent owner so they do not compete. See the Hermes guide.
  • OpenClaw: marmot_group_profile updates the group name or description when the account is an admin. The normal message tool supports react with an emoji, target message id and chat target; remove: true removes it.
  • Claude Code, Codex, OpenCode and Pi: each ordinary turn supplies the shared wn-agent group-profile route for admin name/description updates. The backend needs wn-agent on its PATH and shell/sandbox permission to reach the selected connector's local socket. See the admin profile guide. Harnesses do not provide a built-in reaction tool. A deployment that needs progress reactions must separately configure and verify that capability. Bind every operation to the actual conversation and connector account; never guess a chat from its name, put control secrets in prompts, or start a second writer against the same account home. Verify the installed release exposes the documented command/tool before promising title updates.

Acceptance check on the phone

  1. Invite the bootstrapped agent from the authorized phone account and grant admin in the intended chat when title management is selected.
  2. Select the project for a terminal harness, then send a small ordinary model request. Verify the response lands in that same chat.
  3. If title/reaction tools are configured, verify a meaningful task title and a 👀 → ✅ transition on the request, without a duplicate emoji message. Make a new request to verify session continuity; a status question should keep the task title. Never mark an unavailable command/tool or rejected admin change as passed.
  4. Test one required file type and generated-file return if supported. Check the capability guide before choosing the test.
  5. Report which runtime/profile, connector identity, services and chat were verified, and list remaining phone/tool checks explicitly. A service start, local /status reply or readiness probe alone is not this acceptance check.

Connector capabilities

All seven connectors provide encrypted White Noise conversations with an agent runtime you already use. The runtime supplies the model, tools and permissions; wn-agent supplies Marmot identity, encrypted transport and durable delivery. Choose by the features you need:

Connector Conversation and controls Files
Hermes DM/group activation; history, quotes, reactions, own-message deletion, admin group profile updates; optional live previews/presence/approval reactions Inbound media; image/document/video/voice sends with approved-root staging
OpenClaw Gateway routing; DM/group activation; history, quotes, quiet changes, own-message edits and deletion, reactions, admin group profile updates, consent-based public profile naming; current inbound turns are final-only Host-authorized inbound/outbound media via normal message tool
Claude Code Per-chat session/project/goal; shared chat and recovery commands; admin group profile updates; text replies Text-only; no attachments or generated-file return
Codex Per-chat thread/project/goal; shared chat and recovery commands; admin group profile updates; completed text replies Native images and supported staged files; opt-in generated-file return with exact grants
OpenCode Per-chat session/project/goal; shared chat and recovery commands; admin group profile updates; text-event replies Supported images/PDFs/text; no generated-file return
Pi Per-chat session/project/goal; shared chat and recovery commands; admin group profile updates; completed text replies Supported images/text; no generated-file return
Goose Per-chat session/project/goal; shared chat and recovery commands; text replies between tool calls Text-only; no attachments or generated-file return

For terminal harnesses, start with /cd src/my-project, send an ordinary request, then use /status, /goal <instruction> or /new as needed. The complete chat-command reference explains recovery, session resets and slash escaping. These harnesses do not add gateway mention activation, reaction tools or live previews.

For gateway plugins, ask in the current chat and use the runtime's registered Marmot tools and media-delivery contract. A file accepted by a connector is not a promise that the selected model can interpret it. Voice/audio upload shares the group's configured media endpoint and limits; personal kind-10063 discovery is not yet implemented. Each linked guide explains opt-ins, restrictions and verification steps; installing another connector does not inherit its features.

First-install verification

For a copied White Noise installation prompt, use the connector's first-install checklist and the selected runtime's guide. Resolve the actual runtime/profile home, choose one owner for each connector socket/service, verify the downloaded installer checksum and release cohort, and configure both invitation and message-sender authorization. A successful install/bootstrap is not proof of an agent reply reaching the phone: finish with an invited, allowed-account White Noise round trip.

Before installing, follow the runtime-specific checklist: Hermes, OpenClaw, Claude Code, Codex, OpenCode, Pi, or Goose. The five terminal harnesses also share a two-process/environment verification guide. These guides distinguish invitation authorization from prompt authorization and actual backend replies from local setup/status acknowledgements.

For Hermes files, stage a regular file under the adapter's approved source root before returning MEDIA:<absolute-path>; see the copy-and-send example. The default source root is the connector home's dev/inbound-media, not an arbitrary workspace. OpenClaw and terminal harnesses have their own documented attachment/export contracts; do not apply Hermes's MEDIA: syntax to them.

How The Connectors Fit Together

Current integrations:

  • hermes/marmot - Hermes platform plugin.
  • openclaw/marmot - OpenClaw channel plugin.
  • claude/marmot - wn-claude Claude Code harness binary.
  • codex/marmot - wn-codex Codex harness binary.
  • opencode/marmot - wn-opencode OpenCode harness binary.
  • pi/marmot - wn-pi Pi harness binary.
  • goose/marmot - wn-goose Goose harness binary.
  • terminal-harness - shared hardened runtime for the Claude Code, Codex, OpenCode, Pi, and Goose terminal harnesses.

All integrations are intentionally thin at the Marmot boundary. They do not own MLS state, Nostr transport, local account storage, relay access, QUIC preview transport, or durable encrypted sends. wn-agent owns those concerns and exposes the local marmot.agent-control.v2 newline-delimited JSON protocol over a Unix socket.

Default Install Topology

The release installers are published with the wn-agent-v* release family:

  • scripts/install-hermes-marmot.sh (passive --doctor [--json] report; not delivery proof)
  • scripts/install-openclaw-marmot.sh
  • scripts/install-claude-marmot.sh
  • scripts/install-codex-marmot.sh
  • scripts/install-opencode-marmot.sh
  • scripts/install-pi-marmot.sh
  • scripts/install-goose-marmot.sh
  • scripts/install-wn-agent.sh (connector only, for your own client)

By default the production-shaped installs create separate local agent identities per connector:

Integration Home Same-user service
Hermes $HOME/.marmot-agents/hermes wn-agent-hermes.service / org.marmot.wn-agent.hermes
OpenClaw $HOME/.marmot-agents/openclaw wn-agent-openclaw.service / org.marmot.wn-agent.openclaw
Claude Code harness $HOME/.marmot-agents/claude wn-agent-claude.service / org.marmot.wn-agent.claude plus wn-claude.service / org.marmot.wn-claude
Codex harness $HOME/.marmot-agents/codex wn-agent-codex.service / org.marmot.wn-agent.codex plus wn-codex.service / org.marmot.wn-codex
OpenCode harness $HOME/.marmot-agents/harnesses wn-agent-harnesses.service / org.marmot.wn-agent.harnesses plus wn-opencode.service / org.marmot.wn-opencode
Pi harness $HOME/.marmot-agents/pi wn-agent-pi.service / org.marmot.wn-agent.pi plus wn-pi.service / org.marmot.wn-pi
Goose harness $HOME/.marmot-agents/goose wn-agent-goose.service / org.marmot.wn-agent.goose plus wn-goose.service / org.marmot.wn-goose
wn-agent only $HOME/.marmot-agents/standalone wn-agent-standalone.service / org.marmot.wn-agent.standalone

Each home derives its own default socket at $MARMOT_HOME/dev/wn-agent.sock and uses the public relay defaults shared with the phone app pilot setup. Claude Code, Codex, OpenCode, Pi, and Goose use separate connector homes and Marmot identities by default. They share implementation in integrations/terminal-harness, but they do not share prompts, sessions, sockets, or services unless an operator explicitly configures a shared deployment.

Hermes and OpenClaw install or patch their host-runtime plugin configuration and then print restart guidance for the existing gateway. They do not restart the gateway automatically. wn-claude, wn-codex, wn-opencode, wn-pi, and wn-goose each install their own harness binary and service in addition to wn-agent, because they are standalone harnesses rather than plugins loaded by an existing gateway.

Identity Model

The default topology creates or reuses one Marmot account per connector home, which means Hermes, OpenClaw, Claude Code, Codex, OpenCode, Pi, and Goose present as separate Nostr identities when installed with default options.

Within each home, wn-agent bootstrap lists local-signing accounts and reuses one when selection is unambiguous. If no local account exists, bootstrap creates one. If more than one local-signing account exists, production integrations should require an explicit account id instead of guessing.

The installers persist the selected account into connector-specific config:

  • Hermes uses MARMOT_ACCOUNT_ID_HEX or the Marmot plugin config.
  • OpenClaw uses channels.marmot.accountIdHex or MARMOT_ACCOUNT_ID_HEX.
  • wn-claude uses WN_CLAUDE_ACCOUNT_ID_HEX.
  • wn-codex uses WN_CODEX_ACCOUNT_ID_HEX.
  • wn-opencode uses WN_OPENCODE_ACCOUNT_ID_HEX.
  • wn-pi uses WN_PI_ACCOUNT_ID_HEX.
  • wn-goose uses WN_GOOSE_ACCOUNT_ID_HEX.

Installing all seven connectors on one machine with default options therefore creates distinct agent identities and distinct chat/group memberships.

What Is Shared

Within one connector home, the host integration and its wn-agent share:

  • the local Marmot account and Nostr public key;
  • the local MLS/group state and app runtime projection;
  • relay configuration and key-package/profile publication through wn-agent;
  • the account-scoped welcomer allowlist used for invite acceptance;
  • the local control socket and optional bearer-token gate;
  • durable sends, deletes, media download staging, and idempotency handled by wn-agent;
  • the inbound event stream exposed by SubscribeInbound.

Across different default connector homes, those items are not shared.

Advanced deployments can still point multiple integrations at the same MARMOT_HOME and socket. The control socket supports multiple clients, and multiple integrations can subscribe to inbound events for the same account at the same time.

What Is Separate

Each host runtime keeps its own runtime state:

  • Hermes keeps Hermes gateway/plugin state under HERMES_HOME.
  • OpenClaw keeps OpenClaw gateway/channel state under OPENCLAW_HOME.
  • wn-claude keeps harness configuration in $MARMOT_HOME/dev/wn-claude.env and session state under $XDG_STATE_HOME/wn-claude by default.
  • wn-codex keeps harness configuration in $MARMOT_HOME/dev/wn-codex.env and session state under $XDG_STATE_HOME/wn-codex by default.
  • wn-opencode keeps harness configuration in $MARMOT_HOME/dev/wn-opencode.env and session state under $XDG_STATE_HOME/wn-opencode by default.
  • wn-pi keeps harness configuration in $MARMOT_HOME/dev/wn-pi.env, connector state under $XDG_STATE_HOME/wn-pi, and Pi sessions under $MARMOT_HOME/dev/pi-sessions by default.
  • wn-goose keeps harness configuration in $MARMOT_HOME/dev/wn-goose.env and connector state under $XDG_STATE_HOME/wn-goose by default. Goose sessions live in the operator's Goose session store, or under WN_GOOSE_PATH_ROOT when that is set.

Each integration also makes its own activation decision:

  • Hermes and OpenClaw are gateway/channel integrations. Each applies its own inbound sender ACL before activation. In multi-party groups they default to mention-style activation and always reply in effective DMs. Activation cannot widen sender authorization. They also support richer gateway features such as live previews, durable reply routing, profile onboarding, and media handling.
  • wn-claude, wn-codex, wn-opencode, wn-pi, and wn-goose are pure harnesses. They currently support only always activation for prompt messages from explicitly allowed senders, and have no profile onboarding or live-preview behavior. Their shared runtime validates and privately stages bounded ordered attachment batches. wn-codex maps image batches to ordered Codex image inputs; wn-opencode passes each file as an ordered opencode run --file argument; wn-pi passes each image or UTF-8 text file as an ordered @file operand and rejects the whole batch before spawning Pi if any file is another type; wn-claude and wn-goose reject every non-empty batch, including its accompanying text, before spawning their backend.

Because activation is per integration, there is no global "claim this message" lease in shared-account deployments. If several integrations subscribe to the same account and group, every eligible integration can reply. For example, a direct message from an allowlisted sender could trigger Hermes/OpenClaw, wn-claude, wn-codex, wn-opencode, wn-pi, and wn-goose if all are running and configured for that account.

Allowlist Behavior

The wn-agent welcomer allowlist is account-scoped, not integration-scoped. In the default installer topology that means each connector has its own allowlist. It matters most when several integrations are intentionally configured to manage the same account.

Invite admission defaults to allowlist. Public direct-message bots can opt in without enabling debug controls by rerunning bootstrap with --invite-policy any-authenticated-direct; this accepts an authenticated welcomer only when the resulting MLS group has exactly two members. The other explicit policies are deny, allowlist, and any-authenticated (which also admits multi-party groups). These account-scoped invite policies remain independent from each integration's sender and activation policy.

Hermes and OpenClaw can mirror configured allowFrom/welcomer entries into wn-agent. That mirroring is invite admission only. Hermes and OpenClaw each keep a separate inbound sender ACL (MARMOT_ALLOWED_USERS / MARMOT_ALLOW_ALL_USERS, plus OpenClaw channels.marmot.senderPolicy) and do not treat membership or welcomer status as authorization to invoke the agent. Their welcomer sync path is config-driven and may reconcile the connector allowlist to the configured set. All terminal harnesses require at least one allowed sender and install those senders into both the prompt allowlist and the wn-agent welcomer allowlist. Their startup mirroring is additive: removing a sender only from wn-agent is not a full harness revoke while the sender remains in WN_CLAUDE_ALLOWED_SENDERS_HEX, WN_CODEX_ALLOWED_SENDERS_HEX, WN_OPENCODE_ALLOWED_SENDERS_HEX, or WN_PI_ALLOWED_SENDERS_HEX.

For shared-account deployments, prefer one explicit source of truth for the account's allowed welcomers, or configure every integration with the same intended union.

Sharing Options

Run the default installers when you want each connector to appear as its own agent identity.

Use an explicit shared deployment when you want one Marmot identity behind several integrations:

  • one shared MARMOT_HOME;
  • one shared MARMOT_AGENT_SOCKET;
  • one wn-agent service owning that socket;
  • explicit account ids in each integration config;
  • --no-service for secondary installers, or manual service units with a single owner for the shared socket;
  • separate host-runtime homes such as HERMES_HOME and OPENCLAW_HOME if the gateway runtimes themselves should stay isolated.

The current Hermes, OpenClaw, and terminal-harness release installers are optimized for isolated defaults. They also expose MARMOT_HOME, MARMOT_AGENT_SOCKET, MARMOT_AGENT_LABEL, MARMOT_AGENT_SERVICE_NAME, and MARMOT_AGENT_LAUNCHD_LABEL overrides for advanced layouts.

If wn-agent and a host gateway run as different local users, keep the socket Unix-domain only and use the existing socket mode plus bearer-token options: --auth-token-file, group-readable socket modes, and MARMOT_AGENT_AUTH_TOKEN_FILE.

That bearer is a full-daemon credential, not an account selector or a read-only integration key. A holder can read all inbound plaintext and perform every control operation for every account in that connector home. Share a connector only among integrations in the same trust boundary. For a less-trusted plugin, gateway, or tenant, use another wn-agent home, socket, token, and account.

Development Paths

Each integration has its own README and AGENTS file for local details. Common entry points from the repo root:

just hermes-dev-script-test
just hermes-dev-e2e-deterministic
just hermes-dev-e2e-connector

just openclaw-dev-test
just openclaw-dev-script-test
just openclaw-dev-e2e-connector

cargo test -p wn-claude
just claude-dev-e2e-connector
just claude-installer-test

cargo test -p wn-codex
just codex-dev-e2e-connector
just codex-installer-test

cargo test -p wn-opencode
just opencode-dev-e2e-connector
just opencode-installer-test

cargo test -p marmot-terminal-harness

cargo test -p wn-pi
just pi-dev-e2e-connector
just pi-installer-test

cargo test -p wn-goose
just goose-dev-e2e-connector
just goose-installer-test

just wn-agent-installer-test

For release-installer work, test dry-runs and real release assets from the wn-agent-v* release family. Do not assume a source checkout script exactly matches the published installer.

Prev
C and native hosts
Next
Terminal and scripts
Protocol
Development Kit
Documentation
Apps
Awesome
Releases
Community
GitHub
Donate
Contact
©2025–2026 Internet Privacy Foundation. All rights reserved.
Marmot