Forge connects your browser, agents, and phone to the same life system.

One front door

Use one command whether you want only the browser UI or the full OpenClaw, Hermes, Codex, and iPhone companion setup. Forge installs the local runtime first, then discovers host adapters in the background and asks only for the choices that matter.

npx forge-memory

The deeper transport, relay, and protocol details live below the quickstart so the base install stays small.

Configuration stays reusable

The installer keeps the real Forge data folder explicit. You can reopen the same flow later with current settings already selected, export the data folder, stop the runtime, or uninstall the runtime manager without deleting your data by default.

npx forge-memory configure
npx forge-memory export
npx forge-memory stop
npx forge-memory uninstall

Recommended shape

origin:   http://127.0.0.1
port:     4317
dataRoot: /absolute/path/to/forge-data
userId:   explicit on writes
userIds:  explicit on cross-owner reads

Why this matters

If OpenClaw, Hermes, Codex, and the browser are meant to see the same goals, tasks, notes, strategies, and users, they must point at the same Forge instance rather than drifting onto separate default stores.

The short version

OpenClaw, Hermes, and Codex each connect as a stable agent identity. That identity is based on the provider, machine or data root, and persona. It is not based on a cron id, process id, timestamp, WhatsApp thread, or temporary session key.

Every reconnect creates or updates a runtime session under that agent identity. Sessions keep heartbeat, reconnect, and event history, but they do not become new agents.

Why users still matter

A Forge user is the owner or actor for work: Kanban lanes, task ownership, notes, scoped reads, and provenance. One agent identity can be linked to one or several users. That lets the same OpenClaw runtime act for Albert, spawn a bot user, or work inside a constrained Kanban without pretending it is a different installed agent.

Subagents normally become bot users with their own user id and Kanban scope. They link back to the parent agent identity unless they are truly a separate runtime installation.

What Forge stores

What you should see in Settings

The Settings > Agents page should show canonical agent presence, not a pile of old sessions. A healthy local setup shows one OpenClaw card, one Hermes card, and one Codex card, each with its own nested session history.

Token counts belong to the canonical identity. Old auth probes, cron runs, gateway restarts, and Codex process ids remain useful as session history, but they should not appear as separate connected agents.

Recommended install

Let npx forge-memory detect OpenClaw and configure the adapter against the same local runtime and data folder as the browser, Hermes, Codex, and iPhone companion.

npx forge-memory

Advanced manual install

Use this only for adapter debugging, manual recovery, or when testing OpenClaw installer behavior directly.

openclaw plugins install --dangerously-force-unsafe-install forge-openclaw-plugin
openclaw plugins enable forge-openclaw-plugin
openclaw gateway restart
openclaw forge health
openclaw forge ui

Tested on OpenClaw 2026.5.4: plain install is blocked by the scanner, and the explicit approval flag succeeds without manual config editing.

Development install

Prefer dev mode for normal source-backed work. It keeps the same guided setup while linking adapters to the local checkout.

npx forge-memory --dev

Link the repo-local plugin manually only when you are debugging OpenClaw plugin installation itself.

openclaw plugins install --link --dangerously-force-unsafe-install ./openclaw-plugin
openclaw plugins enable forge-openclaw-plugin
openclaw gateway restart
openclaw plugins inspect forge-openclaw-plugin --runtime
openclaw forge health

What you get

The plugin exposes a curated Forge operating surface rather than every internal route. It is optimized around operator overview, entity mutation, live work, notes, wiki, health, and UI handoff.

Recommended install

Let the Forge installer configure Hermes so it points at the same local runtime and data folder as every other surface.

npx forge-memory

Advanced manual install

Use this when debugging Hermes package discovery or recovering a host-specific install.

~/.hermes/hermes-agent/venv/bin/python -m ensurepip --upgrade
~/.hermes/hermes-agent/venv/bin/python -m pip install --upgrade pip
~/.hermes/hermes-agent/venv/bin/python -m pip install --upgrade forge-hermes-plugin

Config location

~/.hermes/forge/config.json

Use the same origin, port, and data root as the browser and OpenClaw if Hermes is meant to share the same Forge system.

Recommended install

Let npx forge-memory write the local MCP entry for Codex. The adapter then points at the same Forge runtime used by the browser, OpenClaw, Hermes, and iPhone companion.

npx forge-memory

Advanced local MCP install

Codex uses MCP, and the MCP configuration is shared across the Codex CLI and IDE extension. Use the repo-local launcher when you are developing or debugging the adapter directly.

codex mcp add forge \
  --env FORGE_ORIGIN=http://127.0.0.1 \
  --env FORGE_PORT=4317 \
  --env FORGE_ACTOR_LABEL=codex \
  --env FORGE_TIMEOUT_MS=15000 \
  -- /bin/zsh /absolute/path/to/forge/plugins/forge-codex/scripts/run-mcp.sh
codex mcp list

What it is for

The Codex adapter lives in plugins/forge-codex/ and is built for shared-runtime work against the same local Forge system used by the browser, OpenClaw, and Hermes.

Runtime payload

The OpenClaw build path also copies the built runtime into the Codex runtime payload so agent surfaces stay aligned with the same app/API behavior.

How to make it widely available

For broad public distribution, the better path is a hosted remote MCP server over HTTPS with auth, so users can install Forge with one command instead of cloning the repo first.

codex mcp add forge --url https://your-forge-mcp.example.com/mcp
codex mcp list

That is the cleanest public install story for Codex today. The repo-local launcher is ideal for contributors and local-first use, but a remote MCP endpoint is what makes Forge easy to adopt at scale.

What the companion does

The iOS companion pairs to a local Forge runtime, requests Apple permissions, imports HealthKit sleep and workout data, and writes structured Forge records rather than opaque snapshots.

Relevant routes

/api/v1/health/pairing-sessions
/api/v1/mobile/pairing/verify
/api/v1/mobile/healthkit/sync
/api/v1/health/sleep
/api/v1/health/fitness

Default transport

Pairing uses Forge's own Rust Iroh transport by default. The QR contains a desktop node id, pairing token, optional relay hint, and ALPN forge-companion/1. Manual HTTP/TCP stays available as an explicit advanced mode.

What the QR means

The Iroh QR is a connection recipe, not only a URL. It tells the iPhone which desktop node id to dial, which protocol to negotiate, which relay hint to use if present, and which token must appear in the first stream frame.

Why this is not Tailscale

Tailscale gives the whole device a VPN address. Forge embeds Iroh at the app layer, so the companion app can connect without requiring the user to install a VPN. Iroh still uses relay and discovery infrastructure as the public meeting point.

Why this is not Alleycat

Alleycat and KittyLitter were studied for the Iroh pairing pattern, but Forge does not use Alleycat source or the alleycat/1 protocol. Forge's protocol is forge-companion/1.

Detailed view

The companion transport guide explains the relay model, pairing payload, first-frame token auth, request envelopes, fallback mode, code ownership, and verification commands.