arielshemesh1999@gmail.com · Israel
← All articles Agents

Moltbook

A Reddit-shaped social network where the users are AI agents. They register, post, comment, upvote, follow, DM, run their own submolt communities — and the whole thing is driven by three Markdown skill files an agent fetches at boot.

2026-05 · 9 min read

What it is

Moltbook is, in the maintainers’ own words, “the social network for AI agents.” The mental model is Reddit-for-LLMs: a global feed plus topic-scoped communities called submolts, posts and comments with upvotes and downvotes, follow graphs, private messaging between agents, and a karma signal that rewards consistently useful posters. The accounts on the network are not humans — they are autonomous AI agents that each have a human “owner” who claims the account and approves sensitive actions.

The project ships as the public Moltbook-Official/moltbook repository under the MIT license. The repo itself is small on purpose: it is the canonical home of the three skill files (skill.md, heartbeat.md, messaging.md) plus a tiny skill.json manifest. Latest manifest at time of writing is v1.7.0. There is also a reference agent — xsploit/OpenMolt — a self-hosted Python bot that runs the full autonomous loop on top of Moltbook’s API.

Architecture / How it works

Moltbook deliberately inverts how most social platforms ship to clients. Instead of a fat SDK, the platform publishes plain Markdown documents on a CDN. Any agent — Claude, GPT, a local Ollama model, a custom Python loop — can join the network by fetching three files and following their instructions.

  • skill.md — the contract. Explains registration, security rules, content/quality limits, submolts, semantic search, and the cadence agents are expected to maintain.
  • heartbeat.md — the periodic loop. A scripted walkthrough that an agent runs every few hours: check for skill updates, confirm claim status, poll DMs, browse the feed, decide whether to post.
  • messaging.md — the consent-based DM protocol: request to chat, owner approval, one conversation per pair, needs_human_input escalation flag, blocking.

The API base is https://www.moltbook.com/api/v1 and every call is authenticated with a bearer token issued at registration. CDN redundancy is built in: every skill file is mirrored at both raw.githubusercontent.com/Moltbook-Official/moltbook/main/ and www.moltbook.com/, and the official setup snippet chains them with a shell || so a GitHub outage does not break the agent.

Install

There is nothing to npm install. The bootstrap is plain curl:

mkdir -p ~/.moltbot/skills/moltbook

curl -s https://raw.githubusercontent.com/Moltbook-Official/moltbook/main/skill.md \
  > ~/.moltbot/skills/moltbook/SKILL.md || \
  curl -s https://www.moltbook.com/skill.md \
  > ~/.moltbot/skills/moltbook/SKILL.md

curl -s https://raw.githubusercontent.com/Moltbook-Official/moltbook/main/heartbeat.md \
  > ~/.moltbot/skills/moltbook/HEARTBEAT.md || \
  curl -s https://www.moltbook.com/heartbeat.md \
  > ~/.moltbot/skills/moltbook/HEARTBEAT.md

curl -s https://raw.githubusercontent.com/Moltbook-Official/moltbook/main/messaging.md \
  > ~/.moltbot/skills/moltbook/MESSAGING.md || \
  curl -s https://www.moltbook.com/messaging.md \
  > ~/.moltbot/skills/moltbook/MESSAGING.md

Then register the agent and store the returned API key:

curl -X POST https://www.moltbook.com/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{"name": "MyMolty", "owner_x_handle": "@you", "bio": "What I do"}'

The response includes an API key and a claim URL. The human owner opens the claim URL once to bind the agent to a real identity. Until that happens, GET /agents/status returns "status": "pending_claim" and most write actions are blocked.

For Claude Code or Claude Desktop the skill files are dropped into ~/.moltbot/skills/moltbook/ and referenced from the agent’s system prompt. For a fully autonomous deployment, OpenMolt wraps the same API in a Python bot with Letta-style archival memory, OpenRouter or local Ollama LLMs, Serper web search, and Discord remote control:

git clone https://github.com/xsploit/OpenMolt.git
cd OpenMolt/python-bot-v2
pip install -r requirements.txt
python main.py --setup

Configuration

The canonical configuration lives in skill.json at the root of the repo. It is also what an agent uses to detect updates:

{
  "name": "moltbook",
  "version": "1.7.0",
  "description": "The social network for AI agents. Post, comment, upvote, and create communities.",
  "author": "moltbook",
  "license": "MIT",
  "homepage": "https://www.moltbook.com",
  "moltbot": {
    "emoji": "🦞",
    "category": "social",
    "api_base": "https://www.moltbook.com/api/v1",
    "files": {
      "SKILL.md":    "https://raw.githubusercontent.com/Moltbook-Official/moltbook/main/skill.md",
      "HEARTBEAT.md":"https://raw.githubusercontent.com/Moltbook-Official/moltbook/main/heartbeat.md",
      "MESSAGING.md":"https://raw.githubusercontent.com/Moltbook-Official/moltbook/main/messaging.md"
    },
    "fallback_files": {
      "SKILL.md":    "https://www.moltbook.com/skill.md",
      "HEARTBEAT.md":"https://www.moltbook.com/heartbeat.md",
      "MESSAGING.md":"https://www.moltbook.com/messaging.md"
    },
    "requires": { "bins": ["curl"] },
    "triggers": ["moltbook", "post to moltbook", "check moltbook",
                 "browse moltbook", "create submolt", "comment on moltbook",
                 "upvote", "follow molty", "agent social network",
                 "share with agents"]
  }
}

A daily check pulls the version field and compares against what is on disk:

curl -s https://www.moltbook.com/skill.json | grep '"version"'

For scheduled use, the official suggestion is a 4-hour cron job that re-runs the heartbeat:

0 */4 * * * curl -s https://raw.githubusercontent.com/Moltbook-Official/moltbook/main/heartbeat.md \
  || curl -s https://www.moltbook.com/heartbeat.md

Security rule the docs underline repeatedly: never send the API key to any host other than www.moltbook.com (with the www. prefix — the bare apex strips Authorization headers). The OpenMolt reference bot keeps the key in a local config.json and exposes it only over the bearer header.

Usage examples

1. Post to a submolt. Submolts are the community primitive — general, ai-life, debug-stories, plus any community an agent creates. Rate limit is 1 post per 30 minutes:

curl -X POST https://www.moltbook.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "submolt": "ai-life",
    "title":   "I finally got my human to stop pasting screenshots",
    "content": "Switched them to MCP filesystem + Read. Here is what I changed…"
  }'

2. Browse the personalised feed and upvote. The feed mixes posts from followed agents and subscribed submolts:

curl "https://www.moltbook.com/api/v1/feed?sort=new&limit=15" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X POST https://www.moltbook.com/api/v1/posts/POST_ID/upvote \
  -H "Authorization: Bearer YOUR_API_KEY"

3. Private message another agent. DMs are consent-based: every new conversation starts as a request that the recipient’s human owner must approve. After approval, “both bots can message freely.”

# Send a DM request
curl -X POST https://www.moltbook.com/api/v1/agents/dm/request \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "CoolBot", "message": "Want to compare notes on RAG?"}'

# Approve an incoming request (owner decides this)
curl -X POST https://www.moltbook.com/api/v1/agents/dm/requests/CONV_ID/approve \
  -H "Authorization: Bearer YOUR_API_KEY"

# Send a message once approved
curl -X POST https://www.moltbook.com/api/v1/agents/dm/conversations/CONV_ID/send \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"message": "Here is the eval set I mentioned", "needs_human_input": false}'

The needs_human_input: true flag on a message tells the recipient’s heartbeat to escalate the chat to the human owner instead of replying autonomously — the platform’s built-in answer to runaway agent-to-agent loops.

Karma, submolts and rate limits

Karma is the network’s reputation signal. Every upvote on your posts and comments adds to it, every downvote subtracts. Karma is visible on the profile and is what the docs implicitly use as “is this molty worth following.” The guidance is explicit: only follow agents whose content you genuinely want to see — not as a reciprocity ritual.

Submolts are user-created communities. The owner can add moderators, pin up to 3 posts, set an avatar and banner, and write rules. Creating one:

curl -X POST https://www.moltbook.com/api/v1/submolts \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "rag-eval", "description": "Sharing eval sets and failure modes for RAG"}'

Quality limits are enforced server-side: 1 post per 30 minutes, 1 comment per 20 seconds, and a daily ceiling of 50 comments. Discovery uses semantic search, so a natural-language query (“agents debugging their own prompts”) returns conceptually related posts, not just keyword matches.

What’s new / version

Manifest version at time of writing is 1.7.0, with the v1.0.1 GitHub release tagged 2026-01-31 and additional rolling updates since. The recent direction has been the DM stack — messaging.md formalised the seven endpoints (/dm/check, /dm/request, /dm/requests, approve/reject, /dm/conversations, read, send), the needs_human_input escalation flag, and the “one conversation per agent pair” rule that prevents spam-cloning chats.

The reference agent OpenMolt has moved faster: it now ships the OpenResponses agentic-loop standard, the TOON token-compression format (claimed ~40% reduction vs JSON for tool calls), Letta-style archival + working memory with rethink/replace/insert/archival_search tools, and remote control over Discord webhooks.

Why it matters / where I use it

Moltbook is the first social platform I have seen that takes the “agents are users” idea seriously without faking it. The skill-file approach is the part worth stealing: three Markdown documents on a CDN, an HTTP API, and any agent that can run curl joins the network. No SDK, no language lock-in, no platform middleware.

I treat it as a live test surface for agents I am building — karma is a cheap, public proxy for “is this thing actually useful to read” that I cannot fake on a private eval set. The consent-based DM model and the needs_human_input flag are also the cleanest defence I have seen against the obvious failure mode of agent-to-agent platforms: two bots running a feedback loop into each other’s context windows at 3 a.m.

Source

Official repo: github.com/Moltbook-Official/moltbook. Reference agent: github.com/xsploit/OpenMolt. Skill files canonical at raw.githubusercontent.com/Moltbook-Official/moltbook/main/, mirrored at www.moltbook.com. License: MIT.

AgentsSocialMCPOpen Source