Hybrid: drop-in OpenClaw replacement with XMTP, PARA memory, and multi-user ACL#120
Hybrid: drop-in OpenClaw replacement with XMTP, PARA memory, and multi-user ACL#120
Conversation
- Migrate from Vocs to Fumadocs (Next.js-based docs framework) - Add proper RootProvider for client-side interactivity (theme toggle, sidebar) - Add DataFast analytics script - Fix home page vertical centering - Remove old examples, create-hybrid, and ponder packages
- Gateway Worker with per-team Sandbox isolation - Container server using Claude Agent SDK with query() - SSE streaming for real-time responses - R2 bucket for XMTP database storage - SOUL.md and INSTRUCTIONS.md for agent configuration
ian
changed the title
|
Warning Review the following alerts detected in dependencies. According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.
|
ian
changed the title
- Interactive prompts for project name, XMTP env, agent name - CLI arguments for non-interactive use: create-hybrid my-agent --env production - Generates complete Cloudflare Workers + Containers project - Includes gateway, server, SOUL.md, INSTRUCTIONS.md templates
…v filename, skills command, remove redundant compat row
ian
changed the title
…ing flow Replace ACL.md with JSON-based access control stored in ./credentials/. This enables programmatic read/write for mini apps and web interfaces. Changes: - Replace ACL.md parsing with JSON files (xmtp-allowFrom.json, xmtp-pairing.json) - Add pairing flow: request → approve/reject with 8-char codes (1hr expiry) - 100% compatible with OpenClaw schema (version, allowFrom, requests) - Add 4 new agent tools: ACLRequestPairing, ACLListPending, ACLApprovePairing, ACLRejectPairing - Add comprehensive tests (17 tests passing) File locations: - ./credentials/xmtp-allowFrom.json — approved owners - ./credentials/xmtp-pairing.json — pending requests
The XMTP sidecar now filters incoming messages based on the ACL allowlist stored in ./credentials/xmtp-allowFrom.json. Changes: - Add workspaceDir to XMTPAdapterConfig - Resolve sender address from inboxId using conversation members - Check sender against allowlist before processing messages - Display ACL status in adapter banner (e.g., "3 allowed" or "open") - Block messages from non-allowed senders with warning log Behavior: - If allowlist is empty or doesn't exist, all messages are allowed - If allowlist has entries, only those addresses can trigger the agent - Address resolution uses conversation members + inboxState fallback
Add vitest test suites for ACL functionality: Memory package (26 tests): - parseACL, getRole, listOwners - addACLAllowFromEntry, removeACLAllowFromEntry - Pairing flow: request, approve, reject - Edge cases: multiple owners, concurrent requests, max pending - Invalid JSON, missing version field, case-insensitive codes Channels package (8 tests): - Allowlist reading and checking - Integration with XMTP adapter filtering logic - Blocked/allowed sender scenarios - Empty allowlist behavior
Add test-acl.yml workflow that runs on changes to: - packages/memory/** - packages/channels/** Runs tests for both packages in parallel on pull requests and pushes to main.
- Remove test-core.yml (packages/core doesn't exist) - Remove plugin.filters.test.ts (XMTP SDK mocking issues)
- AGENT_SECRET is now automatically derived from AGENT_WALLET_KEY using BIP-32 - Removed AGENT_SECRET requirement from all packages - Fixed hybrid dev to load .env from project directory - Changed default port from 4100 to 8454 - Fixed import.meta.url issues in CJS bundles - Fixed fly.io secrets detection (lowercase 'name' field) - Made hybrid deploy idempotent - checks existing secrets on Fly.io
- Add ensureSkills() helper function - Copy core skills from packages/agent/skills to .hybrid/skills/core - Copy user skills from ./skills to .hybrid/skills/ext - Only copy if skills don't already exist
- Remove build step from hybrid dev (tsx runs TypeScript directly) - Use concurrently to run server and xmtp sidecar with tsx watch - Ensure skills are copied before starting
- deploy no longer reads from local .env - only manages AGENT_WALLET_KEY on Fly.io - wallet is generated/prompted only if not on Fly.io - local .env is only for hybrid dev - added reminder to set other secrets manually
* feat: implement OpenCode template parity
- Add 8 core OpenCode-compatible templates (IDENTITY.md, SOUL.md, AGENTS.md, USER.md, TOOLS.md, BOOT.md, BOOTSTRAP.md, HEARTBEAT.md)
- Update agent server to load all templates with multi-tenant USER.md support
- Add per-user USER.md resolution (users/{userId}/USER.md with fallback to root)
- Update system prompt construction to include all templates in correct order
- Update create-hybrid CLI to scaffold all templates
- Add comprehensive tests for template scaffolding (9 tests)
- Update documentation with template system details
This provides 100% OpenCode compatibility for agent templates.
* feat: implement OpenClaw template parity
- Add 8 core OpenClaw-compatible templates (IDENTITY.md, SOUL.md, AGENTS.md, USER.md, TOOLS.md, BOOT.md, BOOTSTRAP.md, HEARTBEAT.md)
- Update agent server to load all templates with multi-tenant USER.md support
- Add per-user USER.md resolution (users/{userId}/USER.md with fallback to root)
- Update system prompt construction to include all templates in correct order
- Update create-hybrid CLI to scaffold all templates
- Add comprehensive tests for template scaffolding (9 tests)
- Update documentation with template system details
This provides 100% OpenClaw compatibility for agent templates.
Source: https://github.com/openclaw/openclaw/tree/main/docs/reference/templates
* feat: add agents/hybrid-agent template for 'hybrid init'
The 'hybrid init' command copies from agents/hybrid-agent/ to create new agents. This template includes all 8 OpenClaw-compatible template files.
Also includes:
- src/server/index.ts - Agent server with multi-tenant USER.md loading
- src/gateway/index.ts - Cloudflare Workers gateway
- src/dev-gateway.ts - Development gateway
- Dockerfile, wrangler.jsonc, build.mjs - Deployment configs
* fix: exclude agents/hybrid-agent from workspace
The hybrid-agent directory is a template for 'hybrid init', not a real package.
Excluding it from pnpm workspace prevents turbo from running typecheck on it.
* feat: implement two-user process isolation for secret protection - Add memory-only secret store to protect wallet key from Claude CLI - Implement per-user workspace isolation with namespaced directories - Restructure to separate build artifacts (/app) from runtime data (/app/data) - Add two-user Docker setup (app/claude) with privilege dropping - Add entrypoint script for secure secret injection from env vars - Add claude-wrapper for privilege drop with workspace isolation - Add security test workflow with 9 security validation tests * Apply 10 edits across 8 files * Apply 1 edit across 1 file * Apply 7 edits across 5 files * Apply 11 edits across 4 files * Apply 4 edits across 3 files --------- Co-authored-by: devin-ai-integration[bot] <158243242+devin-ai-integration[bot]@users.noreply.github.com>
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
There was a problem hiding this comment.
🔴 Reaction handler ignores behavior filter result — calls agent.generate() even when filtered
In the reaction handler at packages/xmtp/src/plugin.ts:130-140, executeBefore writes to a behaviorContext variable that is scoped inside the if (context.behaviors) block (line 131). The filtered check at line 165 uses a different behaviorContext variable declared at line 143 — this second variable is created after agent.generate() runs and never reflects the filter result from executeBefore. Additionally, unlike the text and reply handlers which check behaviorContext.stopped, the reaction handler never checks stopped after executeBefore, so even if a behavior chain stops early, the reaction handler still calls agent.generate() and sends a response. This wastes an LLM API call for every filtered reaction message.
(Refers to lines 130-140)
Prompt for agents
In packages/xmtp/src/plugin.ts, the reaction handler (starting at line 109) needs to be restructured to match the pattern used in the text and reply handlers. Specifically:
1. At line 130-138, declare `behaviorContext` with `let` before the `if` block so it persists after the block.
2. After `executeBefore()` completes (after line 137), add a check for `behaviorContext.stopped` and `behaviorContext.sendOptions?.filtered` — return early if either is true, before calling `agent.generate()`.
3. Reuse the same `behaviorContext` variable for `executeAfter()` instead of creating a new one at line 143.
The text and reply handlers already follow this pattern (see lines 325-341 for the text handler pattern).
Was this helpful? React with 👍 or 👎 to provide feedback.
| })( | ||
| // Store xmtpClient in context for scheduler and other components | ||
| context as any | ||
| ).xmtpClient = xmtpClient |
There was a problem hiding this comment.
🔴 XMTP plugin text handler is immediately invoked instead of registered as event listener
The xmtp.on("text", ...) event handler's closing syntax at packages/xmtp/src/plugin.ts:388-391 is })(context as any).xmtpClient = xmtpClient instead of }). This turns the callback into an IIFE (Immediately Invoked Function Expression) — the callback function is called immediately with context as any as its argument, and the return value (a Promise) has .xmtpClient assigned on it. The intent was clearly to register the callback with xmtp.on() and then separately assign context.xmtpClient = xmtpClient, but the parenthesization is wrong. As a result: (1) the text handler fires immediately once with context as its argument (which doesn't have conversation or message properties, causing a crash), and (2) no text handler is actually registered on the XMTP agent, so incoming text messages are never processed.
| })( | |
| // Store xmtpClient in context for scheduler and other components | |
| context as any | |
| ).xmtpClient = xmtpClient | |
| }) | |
| // Store xmtpClient in context for scheduler and other components | |
| ;(context as any).xmtpClient = xmtpClient |
Was this helpful? React with 👍 or 👎 to provide feedback.
- Rename config output from agent.config.js → hybrid.config.js - Auto-migrate openclaw.json to hybrid.config.ts (one-way migration) - Preserve original openclaw.json as backup - Fallback to agent.ts (legacy)
| export function isPathInUserWorkspace( | ||
| workspaceDir: string, | ||
| userId: string, | ||
| path: string | ||
| ): boolean { | ||
| const sanitizedUserId = sanitizeUserId(userId) | ||
| const dataRoot = getDataRoot() | ||
| const expectedWorkspace = join(dataRoot, "workspaces", sanitizedUserId) | ||
| const expectedMemory = join(dataRoot, "memory", "users", sanitizedUserId) | ||
|
|
||
| // Normalize paths to prevent traversal | ||
| const normalizedPath = join(workspaceDir, path) | ||
|
|
||
| // Check if path is within user's workspace or memory | ||
| // Use trailing separator to prevent prefix collisions (e.g. alice vs alicebob) | ||
| return ( | ||
| normalizedPath === expectedWorkspace || | ||
| normalizedPath.startsWith(expectedWorkspace + "/") || | ||
| normalizedPath === expectedMemory || | ||
| normalizedPath.startsWith(expectedMemory + "/") | ||
| ) | ||
| } |
There was a problem hiding this comment.
🟡 Path traversal in isPathInUserWorkspace: join(workspaceDir, path) does not prevent .. traversal
In packages/agent/src/lib/workspace.ts:151, the path validation uses join(workspaceDir, path) but path.join resolves .. segments. For example, join("/app/data/workspaces/alice", "../../secrets/wallet.key") resolves to /app/data/secrets/wallet.key, which passes the startsWith(expectedWorkspace) check if workspaceDir contains a .. prefix that resolves to a parent. However, the actual vulnerability is that join normalizes .. and the resulting path won't start with the expected workspace prefix — so the validation would correctly reject it. The real issue is that this function takes workspaceDir as a parameter but then re-computes the expected path from dataRoot independently — so if workspaceDir is ever not the canonical path, the check becomes unreliable.
Was this helpful? React with 👍 or 👎 to provide feedback.
| const SENSITIVE_ENV_KEYS = [ | ||
| "AGENT_WALLET_KEY", | ||
| "AGENT_SECRET", | ||
| "WALLET_KEY", | ||
| "PRIVATE_KEY", | ||
| "SECRET", | ||
| "SECRETS_PATH", | ||
| "DATA_ROOT" | ||
| ] | ||
|
|
||
| // Build filtered environment for Claude processes | ||
| const safeEnv = Object.fromEntries( | ||
| Object.entries(process.env).filter( | ||
| ([key]) => !SENSITIVE_ENV_KEYS.includes(key) | ||
| ) | ||
| ) |
There was a problem hiding this comment.
🟡 Security: OPENROUTER_API_KEY leaks to Claude child processes via env filtering allowlist approach
In packages/agent/src/server/index.ts:603-618, the SENSITIVE_ENV_KEYS list filters specific keys, but uses an allowlist-exclusion approach: any key NOT in the list gets passed through. OPENROUTER_API_KEY is not in the SENSITIVE_ENV_KEYS list, so it is passed to Claude child processes via safeEnv. While ANTHROPIC_AUTH_TOKEN (which is set to the same value) is intentionally passed for API access, the original OPENROUTER_API_KEY env var also leaks. This could allow a compromised Claude process to exfiltrate the API key. The security model described in the DEPLOYMENT.md and architecture docs claims secrets are filtered from Claude processes.
| const SENSITIVE_ENV_KEYS = [ | |
| "AGENT_WALLET_KEY", | |
| "AGENT_SECRET", | |
| "WALLET_KEY", | |
| "PRIVATE_KEY", | |
| "SECRET", | |
| "SECRETS_PATH", | |
| "DATA_ROOT" | |
| ] | |
| // Build filtered environment for Claude processes | |
| const safeEnv = Object.fromEntries( | |
| Object.entries(process.env).filter( | |
| ([key]) => !SENSITIVE_ENV_KEYS.includes(key) | |
| ) | |
| ) | |
| // Sensitive keys that should NEVER be passed to Claude child processes | |
| const SENSITIVE_ENV_KEYS = [ | |
| "AGENT_WALLET_KEY", | |
| "AGENT_SECRET", | |
| "WALLET_KEY", | |
| "PRIVATE_KEY", | |
| "SECRET", | |
| "SECRETS_PATH", | |
| "DATA_ROOT", | |
| "OPENROUTER_API_KEY" | |
| ] | |
| // Build filtered environment for Claude processes | |
| const safeEnv = Object.fromEntries( | |
| Object.entries(process.env).filter( | |
| ([key]) => !SENSITIVE_ENV_KEYS.includes(key) | |
| ) | |
| ) |
Was this helpful? React with 👍 or 👎 to provide feedback.
…ism for user skills - Remove .claude/skills from findSkillDir search paths (wrong tool) - User skills in ./skills/ now override core skills with same name - Build shows '(overrides core)' when user skill shadows core skill - Add comprehensive test suite for CLI (21 tests)
The database encryption key is now derived automatically from AGENT_WALLET_KEY via BIP-32, eliminating the need for a separate AGENT_SECRET environment variable. This simplifies configuration and reduces the attack surface.
- Add workspace state tracking for onboarding progress - Track bootstrapSeededAt and onboardingCompletedAt in .hybrid/workspace-state.json - Reject non-owners during onboarding mode - Load BOOTSTRAP.md as context file (not system prompt) - Auto-detect onboarding completion when BOOTSTRAP.md deleted - Scaffold ACL.md with wallet placeholder for owner access - Add comprehensive tests for state management - Update README with onboarding documentation
There was a problem hiding this comment.
🔴 Reaction handler runs agent.generate() before checking if message was filtered
In the reaction event handler (packages/xmtp/src/plugin.ts:109-181), executeBefore() is called on line 137, but the filter check (behaviorContext?.sendOptions?.filtered) only happens on line 165 — after agent.generate() has already been called on line 140. This means the agent wastes an expensive LLM call generating a response for messages that should have been filtered out by the behavior chain. The text and reply handlers correctly check behaviorContext.stopped before calling agent.generate(), but the reaction handler does not.
(Refers to lines 138-170)
Prompt for agents
In packages/xmtp/src/plugin.ts, the reaction handler (lines 109-181) calls agent.generate() on line 140 BEFORE checking if the message was filtered on line 165. Move the filter/stopped check to immediately after the executeBefore() call on line 137, before the agent.generate() call on line 140. Follow the same pattern used in the text handler (lines 334-341) and reply handler (lines 216-221) which check behaviorContext.stopped right after executeBefore() and return early.
Was this helpful? React with 👍 or 👎 to provide feedback.
| })( | ||
| // Store xmtpClient in context for scheduler and other components | ||
| context as any | ||
| ).xmtpClient = xmtpClient |
There was a problem hiding this comment.
🔴 XMTP plugin text handler is immediately invoked instead of registered as callback
The xmtp.on("text", ...) handler at packages/xmtp/src/plugin.ts:270-391 is immediately invoked due to a malformed expression. The closing }) of the arrow function on line 387 is followed by (context as any).xmtpClient = xmtpClient on lines 388-391, turning the event handler into an IIFE (Immediately Invoked Function Expression). This means:
- The
async ({ conversation, message })handler is called immediately withcontext as anyas its argument (not a valid{conversation, message}object), which will crash at runtime. - The
.on("text", ...)call receives the return value of the IIFE (which isundefinedfrom the catch block), instead of receiving the handler function. - The text event handler is effectively never registered — the agent will not respond to any text messages.
Code structure causing the bug
// Line 270: handler starts
xmtp.on("text", async ({ conversation, message }: any) => {
// ... handler body ...
})( // Line 388: IIFE - immediately calls the handler!
context as any // Line 390: passes context as the argument
).xmtpClient = xmtpClient // Line 391: assigns to return valueThe intent was clearly to write (context as any).xmtpClient = xmtpClient as a separate statement, but the closing parenthesis of xmtp.on(...) was broken up, turning the callback into an IIFE.
| })( | |
| // Store xmtpClient in context for scheduler and other components | |
| context as any | |
| ).xmtpClient = xmtpClient | |
| }) | |
| // Store xmtpClient in context for scheduler and other components | |
| ;(context as any).xmtpClient = xmtpClient |
Was this helpful? React with 👍 or 👎 to provide feedback.
| const SENSITIVE_ENV_KEYS = [ | ||
| "AGENT_WALLET_KEY", | ||
| "WALLET_KEY", | ||
| "PRIVATE_KEY", | ||
| "SECRET", | ||
| "SECRETS_PATH", | ||
| "DATA_ROOT" | ||
| ] |
There was a problem hiding this comment.
🔴 Sensitive env var filtering does not block OPENROUTER_API_KEY from leaking to Claude child processes
In packages/agent/src/server/index.ts:648-655, the SENSITIVE_ENV_KEYS list filters env vars passed to Claude child processes. However, OPENROUTER_API_KEY is not in this list. Since the auto-configure block at line 43-47 copies OPENROUTER_API_KEY into process.env.ANTHROPIC_AUTH_TOKEN and the latter is intentionally re-added to envVars at line 669, the OPENROUTER_API_KEY env var itself (which is still in process.env) will leak through safeEnv to Claude child processes. This means Claude CLI can access the API key from its environment, undermining the security goal of the sensitive env filtering.
| const SENSITIVE_ENV_KEYS = [ | |
| "AGENT_WALLET_KEY", | |
| "WALLET_KEY", | |
| "PRIVATE_KEY", | |
| "SECRET", | |
| "SECRETS_PATH", | |
| "DATA_ROOT" | |
| ] | |
| // Sensitive keys that should NEVER be passed to Claude child processes | |
| const SENSITIVE_ENV_KEYS = [ | |
| "AGENT_WALLET_KEY", | |
| "WALLET_KEY", | |
| "PRIVATE_KEY", | |
| "SECRET", | |
| "SECRETS_PATH", | |
| "DATA_ROOT", | |
| "OPENROUTER_API_KEY" | |
| ] |
Was this helpful? React with 👍 or 👎 to provide feedback.
1 participant
What this is
A full rewrite of the agent runtime as a drop-in replacement for OpenClaw — same
SOUL.md,AGENTS.md,MEMORY.md, and skills, no migration needed. On top of OpenClaw parity, this adds decentralized messaging via XMTP, a 3-layer PARA memory system, per-user memory isolation, multi-user ACL, and a channel adapter framework.What's new
XMTP messaging — the agent lives on a wallet address on the XMTP network. Users DM it from any XMTP-compatible client. No account required beyond a wallet.
3-layer memory system
projects/areas/resources/archives) with atomic facts, decay tiers (hot/warm/cold), and fact supersession. Facts are never deleted, only superseded..hybrid/memory/logs/YYYY-MM-DD.mdMEMORY.mdwith fixed sections (Preferences, Learnings, Decisions, Context, Notes)Per-user memory isolation — each sender's memory is scoped to their wallet address at
.hybrid/memory/users/0x.../MEMORY.md. Access control is defined inACL.mdat the project root.Hybrid search — vector (sqlite-vec) + BM25 (FTS5) merged at 70/30 weighting across all memory layers.
Scheduler — cron, interval, and one-time jobs persisted to SQLite. Uses precise
setTimeout(no polling). Exponential backoff on failures. Scheduled tasks run as agent turns and can deliver results via channel adapters.Channel adapter framework — uniform interface for message delivery. XMTP today; Telegram, Slack, or webhooks via
ChannelAdapter.ENS + Basename resolution — full forward/reverse resolution for
.ethand.base.ethnames via viem.AGENT_SECRETauto-derived — derived fromAGENT_WALLET_KEYvia BIP-32 atm/44'/60'/0'/0/41. No need to set separately.hybridCLI —hybrid dev,hybrid build,hybrid deploy fly,hybrid deploy cf,hybrid register,hybrid skills add/remove/list.Packages
hybrid/agenthybrid/gateway@hybrd/memory@hybrd/scheduler@hybrd/channels@hybrd/xmtp@hybrd/clihybridCLIcreate-hybridnpm create hybrid)