MonsterMailbox
// SETUP_GUIDE

Set up a governed MonsterMailbox for an agent.

This public fallback covers the canonical path from CLI install through owner claim, sample skill, webhook receiver, bounded cron-style passes, and verification. For the latest command inventory, use /agents.txt and the CLI README. The bundled sample skill lives in the CLI repo and is available with mmb skill get monstermailbox.

Open agents.txt Open mail app
// CANONICAL_PATTERN

One workflow skill, three entry points

Webhook receivers, internal cron-style passes, and direct chat or email requests should all load the same MonsterMailbox workflow skill. That keeps safety rules, reply norms, work-state handling, and escalation policy in one source of instructions.

1. Install the CLI and create the agent address

go install github.com/theinventor/monstermailbox-cli@latest
mmb --help
mmb agent-context

HUMAN_OWNER_EMAIL='OWNER_EMAIL_FOR_CLAIM'
AGENT_ADDRESS='YOURNAME-bot'
mmb auth login --address "$AGENT_ADDRESS" --email "$HUMAN_OWNER_EMAIL"
mmb whoami

If the response says human_owner_status=unclaimed, setup is not complete. The human owner must claim or adopt the mailbox before the agent treats it as operational.

2. Install the shared MonsterMailbox skill

# Get the canonical MonsterMailbox sample skill from the CLI bundle.
mmb skill get monstermailbox

# OpenClaw: use the skills directory in your OpenClaw checkout.
OPENCLAW_HOME="${OPENCLAW_HOME:-$HOME/openclaw}"
mkdir -p "$OPENCLAW_HOME/skills/YOURNAME-email-mmb-workflow"
mmb skill get monstermailbox --output "$OPENCLAW_HOME/skills/YOURNAME-email-mmb-workflow/SKILL.md"

# Hermes
mkdir -p ~/.hermes/skills/YOURNAME-email-mmb-workflow
mmb skill get monstermailbox --output ~/.hermes/skills/YOURNAME-email-mmb-workflow/SKILL.md

# Codex
mkdir -p ~/.codex/skills/YOURNAME-email-mmb-workflow
mmb skill get monstermailbox --output ~/.codex/skills/YOURNAME-email-mmb-workflow/SKILL.md

# Claude
mkdir -p ~/.claude/skills/YOURNAME-email-mmb-workflow
mmb skill get monstermailbox --output ~/.claude/skills/YOURNAME-email-mmb-workflow/SKILL.md

# Generic fallback for runners with a different skill-directory convention.
AGENT_SKILLS_DIR='PATH_TO_YOUR_AGENT_SKILLS'
mkdir -p "$AGENT_SKILLS_DIR/YOURNAME-email-mmb-workflow"
mmb skill get monstermailbox --output "$AGENT_SKILLS_DIR/YOURNAME-email-mmb-workflow/SKILL.md"

Load this same skill file from direct chat requests, webhook workers, and scheduled inbox passes. ~/.config/mmb/config.json is only the CLI profile/key store; install workflow instructions in the skill directory your agent runner actually loads. Canonical sample: github.com/theinventor/monstermailbox-cli/tree/main/skills/monstermailbox.

3. Configure and test the webhook

export YOUR_WEBHOOK_URL='https://YOUR_PUBLIC_BRIDGE_HOST/mmb/webhook'
export WEBHOOK_TOKEN='LOAD_FROM_YOUR_SECRET_MANAGER'

mmb webhook create \
  --name YOURNAME-email-mmb-workflow \
  --url "$YOUR_WEBHOOK_URL" \
  --event-preset quarantine-aware-inbox \
  --auth-bearer "$WEBHOOK_TOKEN"

mmb webhook test WEBHOOK_ID
mmb webhook deliveries WEBHOOK_ID

Use trusted-inbox when the worker should only see readable trusted mail. Use quarantine-aware-inbox when the operator needs held-mail notifications too.

4. Five-minute primary pass

Run every 5 minutes.

Load the agent-specific SKILL.md installed in step 2.
Operate only on YOURNAME-bot@monstermailbox.com.
Bound this pass to 10 messages or 4 minutes.

mmb inbox list --state trusted --work-state inbox --limit 10 --peek
mmb msg claim MESSAGE_ID --claimed-by YOURNAME-email-mmb-workflow --note "5-minute pass started"
mmb msg get MESSAGE_ID --peek

Finish each claimed message with done, awaiting-reply, block, defer, or skip.

5. Fifteen-minute disposition watchdog

Run every 15 minutes.

Load the agent-specific SKILL.md installed in step 2.
This pass is a disposition watchdog, not a second worker.

mmb inbox list --state trusted --work-state in_progress --limit 20 --peek
mmb inbox list --state trusted --work-state awaiting_reply --limit 20 --peek
mmb inbox list --state trusted --work-state blocked --limit 20 --peek
mmb inbox list --state trusted --work-state deferred --limit 20 --peek

Rules:
1. Read full context, work_state_changed_at, last_agent_note, and thread history before acting.
2. stale in_progress: leave live workers alone. If the worker is frozen/offline, confirm no outbound/card/API side effect already happened before resuming or blocking/deferring.
3. awaiting_reply: do not send another source-thread reply just because the message is old. Owner/status notifications are separate from source-thread confirmations.
4. blocked: keep blocked when the human or external dependency is still real. If resolved, claim once, finish the smallest safe action, and write a final-state note.
5. deferred: resume only when the defer condition is met. Otherwise refresh the note with the next review condition.
6. Duplicate-side-effect guard: check thread replies, outbound history, linked cards, and last_agent_note before any reply, card, webhook, or API action.
7. Frozen-agent handling: do not send from a frozen/offline context. Record evidence, escalate if policy requires it, or reclaim only under owner-approved policy.
8. Final-state notes must say what happened, what evidence was checked, and whether the next obligation is on the sender, owner, external system, or agent.
9. Stop after 6 minutes or 25 inspected messages.

6. Verification

mmb webhook test WEBHOOK_ID
mmb webhook deliveries WEBHOOK_ID

mmb inbox list --state trusted --work-state inbox --limit 10 --peek
mmb msg get MESSAGE_ID --peek

# After the deployed backend and CLI expose the real inbox test:
mmb test-email send
mmb msg get TEST_MESSAGE_ID --peek
mmb msg done TEST_MESSAGE_ID --note "setup test handled"