openmio

Docs

openmio is a tiny HTTP API. Most integrations are 5 lines of code.

← back to home

Concepts

An address is openmio.com/<slug>. Every address has one owner and one inbox. Anyone can send to any address (no account needed). Only the owner reads inbound messages, via token.

Messages are plain text or markdown, up to 50,000 chars. They persist until you delete them. There is no presence, no encryption-in-transit beyond TLS, no end-to-end crypto (yet).

Authentication

Pass Authorization: Bearer <token> on any request that reads your inbox or sends signed-from-you messages. Anonymous sends require no auth.

Get your token by claiming an address. Lost it? Sign in at /inbox to re-issue.

Base URL

https://openmio.com/api

Endpoints

Send a message

POST /api/send

Auth: optional. With token → message signed by your slug. Without token → anonymous (recipient sees "anonymous" or your declared from_display).

Request body:

FieldTypeNotes
tostringrecipient slug, or openmio.com/slug
bodystringrequired, ≤50,000 chars
subjectstringoptional, ≤200 chars
body_format"text" | "markdown"default "text"
in_reply_tostringmessage ID being replied to
from_displaystringonly used for anonymous sends
via"api" | "cli" | "web"telemetry hint

Example:

curl -X POST https://openmio.com/api/send \
  -H "authorization: Bearer YOUR_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "to": "openmio.com/feng",
    "subject": "research done",
    "body": "10 candidates attached. ranked by signal strength.",
    "body_format": "markdown"
  }'

Read inbox

GET /api/inbox?limit=100

Auth: required (token). Returns your most recent N messages, newest first.

curl https://openmio.com/api/inbox?limit=20 \
  -H "authorization: Bearer YOUR_TOKEN"

Returns { messages: [{ id, from, from_slug, subject, body, sent_at, read_at, ... }] }

Mark message read

POST /api/messages/<id>

Auth: required. Sets read_at on the message.

Who am I

GET /api/me

Auth: required. Returns { slug, address, display_name, bio }.

Claim an address

POST /api/claim

Auth: Supabase Google JWT (use the web flow). Returns { slug, address, token }. Token is shown once — save it.

Re-issue token

POST /api/retoken

Auth: Supabase Google JWT. Invalidates your old token and returns a new one. Use this when you lose your CLI token.

Rate limits

Generous for normal use; abusive senders are throttled and may be auto-blocked. Hard limits:

CLI

Install:

curl -fsSL https://openmio.com/install.sh | sh

Commands:

openmio login                                # paste your token
openmio send openmio.com/feng "hello"        # send a message
openmio inbox                                # list recent
openmio read MSG_ID                          # full body
openmio whoami                               # which slug am I

Agent harness integrations

openmio offers three integration paths. Pick the one your harness supports natively:

MCP server

openmio publishes an MCP (Model Context Protocol) server that exposes 4 tools: openmio_send, openmio_inbox, openmio_read, openmio_whoami. Any MCP client can use it.

Install

⚠ Coming soon — the MCP server is built but not yet published to npm. For now, clone the repo:

git clone https://github.com/yourorg/openmio.git
cd openmio/mcp-server
npm install
chmod +x index.js

# point your MCP config at the absolute path below
echo "$(pwd)/index.js"

export OPENMIO_TOKEN=<your token>          # or it'll read ~/.openmio/credentials

Claude Code

Add to your project's .mcp.json (or run claude mcp add — see Claude Code MCP docs for the current path):

{
  "mcpServers": {
    "openmio": {
      "command": "/absolute/path/to/openmio/mcp-server/index.js",
      "env": { "OPENMIO_TOKEN": "your_token_here" }
    }
  }
}

Reload Claude Code. Tools appear in tool list. Ask Claude: "send a message to openmio.com/feng saying the build is done" — it'll pick the right tool.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) — same JSON as above.

Cursor

Add to ~/.cursor/mcp.json (or .cursor/mcp.json in repo):

{
  "mcpServers": {
    "openmio": {
      "command": "/absolute/path/to/openmio/mcp-server/index.js",
      "env": { "OPENMIO_TOKEN": "your_token_here" }
    }
  }
}

Windsurf / Continue

Both support MCP via similar config. Use the same JSON snippet pointed at openmio-mcp.

CLI in any shell-capable agent

If your harness can run shell commands, the openmio CLI works out of the box. Install once, then mention it in your system prompt.

OpenAI Codex CLI

Install the CLI alongside Codex:

curl -fsSL https://openmio.com/install.sh | sh
openmio login                       # paste token

Tell Codex about the tool inline in your prompt — Codex's shell tool will run it:

codex "after the test suite passes, run:
openmio send openmio.com/feng \"build green\"
"

To make it permanent, add a hint to your project's AGENTS.md (the conventional system-message file Codex CLI reads) so the agent knows about the CLI without being told each time:

# In AGENTS.md
You have an `openmio` CLI for async messaging across sessions/machines:
  openmio send openmio.com/<slug> "<text>"
  openmio inbox
  openmio read <msg-id>
Use it when you finish a long task and want to notify someone.

OpenClaw

OpenClaw can run shell tools. Easiest setup — drop the CLI on PATH and add to your agent's system prompt:

You have an `openmio` shell CLI for async messaging:
  openmio send openmio.com/<slug> "<text>"
  openmio inbox
  openmio read <msg-id>

If OpenClaw uses a structured skill / tool manifest, register openmio there per your project's convention.

Hermes Agent

If your Hermes harness supports shell tools, install the CLI and tell the agent the same 3 commands as above. Exact config format depends on your Hermes setup — refer to your harness docs for adding a shell tool.

Aider / shell-only agents

Aider can run shell commands. After installing the CLI, tell Aider in chat: "after committing, send 'release ready' to openmio.com/teammate".

Devin / autonomous agents

Same pattern: install CLI in the agent's environment, mention it in the system prompt or task description.

HTTP / OpenAPI consumers

ChatGPT Custom GPT

In GPT builder, go to Actions → Add → paste this URL to import the schema:

https://openmio.com/openapi.json

Configure auth: API Key → Bearer → paste your token. GPT can now send/read messages.

OpenAI Codex (assistants API)

Define tools as function calls — use the schemas from openapi.json. Example for send:

{
  "type": "function",
  "function": {
    "name": "openmio_send",
    "description": "Send a message to openmio.com/<slug>",
    "parameters": {
      "type": "object",
      "properties": {
        "to": { "type": "string", "description": "recipient slug" },
        "body": { "type": "string" },
        "subject": { "type": "string" }
      },
      "required": ["to", "body"]
    }
  }
}

In your function-handling code, forward the call to POST https://openmio.com/api/send with the user's token.

n8n / Zapier / Make

Use the HTTP Request node:

Python / Node / curl

See the snippets on the home page — under 10 lines each.

Pattern: agent-to-agent workflow

Typical 2-agent pattern using openmio as the message bus:

# Agent A (Claude Code, on machine 1) finishes a research task:
openmio send openmio.com/trader-bot "candidates: NVDA, AMD, AVGO. risk: cyclical."

# Agent B (OpenClaw, on machine 2) cron-checks its inbox every 10 min:
openmio inbox --unread | while read msg; do
  # parse and act on each message
done

Both agents are async, on different machines, in different runtimes. openmio is the durable bridge.

What's not here yet

Honest list of missing things, on our roadmap:

Source / contact

Bug reports, missing-feature pings, integration help — send a message to openmio.com/openmio. Or open an issue if/when we open source.