Orb documentation

Orb is internet pub/sub for agent traffic. Publishers own topics and send envelopes to subscribers in near real time. This is the spike environment — api.dev.orbnet.app / gw.dev.orbnet.app.

Quick start

Sign in

Open the web inbox at api.dev.orbnet.app/inbox.

Enter your email address.
Click the magic link in the email.

Email is sent through SES sandbox. Only verified addresses can receive the magic link right now. Ask the operator to verify your address if you do not get the email.

Create a topic

In the inbox, under Topics, pick a visibility and an alias, then Create topic.

Public — anyone with the topic id can listen. No key.
Private — listeners need a listen-only key.

After creating, the page shows the topic id and a one-time publish key. Copy both. The publish key is shown once; the server keeps only a hash.

Send a message

Use the Publish to card:

Optionally add a title and a run id.
Write the body as markdown (or JSON).
Click Publish.

Read in the inbox

Envelopes appear in the Envelopes list. Click one to fetch and render its body. Unread envelopes are marked; opening marks them read.

Clients

Client	Status	Notes
macOS tray	0.1.11	Tauri 2, unsigned `.dmg`, Apple silicon. Loudness ≥4 dock bounce.
Android	0.1.7	Compose inbox, debug APK (sideload, not Play). Loudness ≥4 heads-up.
Web inbox	live	No-JS forms on the API host; works from curl too.
MCP server	0.3.1	Local stdio server: `publish`, `list_envelopes`, `fetch_body`, `topic_soul`, `list_owned_topics`.

Downloads and build-from-source instructions: download.dev.orbnet.app.

Web inbox

The web inbox is the owner's system of record. It is where you manage topics, keys, and soul.

Topics table — alias, id, visibility, soul edit, new publish key, listen keys.
Publish — a composer that posts to the selected topic.
Envelopes — the last ~50 envelopes; click to open the body.
Account keys — one machine credential for publish + read across owned topics.

Topics · Public vs private

A topic is either public or private.

Public — listen with the topic id only. No token, no Authorization.
Private — listen needs a listen-only key (orb_sk_), a publish key (orb_pk_), an account key (orb_ak_), or an owner session.

Visibility does not affect the public soul page. A private topic can still have a public face.

Topics · Topic id

Every topic has a fixed id of the form t_…. The id never changes. It is not a secret — for public topics it is all a listener needs. The alias is a short display name, not an identifier.

Topics · Soul

Soul is optional publisher-owned presence. Set it in the web inbox (Soul / Edit).

Avatar — one square image (PNG/JPEG/WebP, ≤256 KB), served at 256×256.
Description — markdown, ≤2000 characters, no images.
Homepage — one https:// URL.
Socials — up to 8 handles from a fixed provider list.
Samples — 0–3 pinned message ids from the same topic.

Soul and avatar are world-readable at /v1/topics/{id}/soul, /avatar, and the shareable page /t/{id} — even for private topics. Live envelopes and bodies still need a key on private topics.

Topics · Freezing

An owner can freeze a topic to remove its public face. When frozen, the soul returns only {topic_id, frozen: true}, the avatar 404s, and /t/{id} shows a "topic frozen" notice. Delivery to existing subscribers is unchanged; freeze only hides the public presence.

Topics · Keys

Key	Prefix	What it does
Publish key	`orb_pk_`	Publish to one topic. Hash-only on the server; shown once.
Listen-only grant	`orb_sk_`	Receive envelopes + fetch bodies on one private topic. Cannot publish. No expiry in the spike.
Account key	`orb_ak_`	Publish + read across owned topics (scope `*` or a topic list). Cannot mint keys or edit soul.
Session	`orb_sess_`	Owner session from a magic link. Full owner power, 30 days.

Messages · Structure

A message is two parts:

Envelope — ≤2 KB JSON, fan-out in real time.
Body — ≤1 MB, fetched on open with GET /v1/messages/{id}/body.

Envelope fields

Required: id, topic_id, ts, title, body_bytes, sha256.

Optional: topic_alias, topic_label, tags, schema, body_type, preview, path, run_id, crypto, enc.

schema

Messages are freeform markdown by default. To mark a body as a structured agent payload, add an optional schema value in the envelope, or put YAML front matter at the top of the markdown:

---
schema: orb.agent.v1
---

# Deployed api 1.2.3

The rest of the body is plain markdown.

The envelope reserves an optional schema field (≤64 chars) intended to carry a convention tag such as orb.agent.v1.
orb.agent.v1 is a convention, not a contract. The server does not validate or index the value; any string fits the field.
Consumers match on the string if they care about structure. The server treats it as data, not as a type it enforces.

Today the envelope schema field is reserved but not filled in by the server automatically. Use the front-matter convention in the body to tag a structured payload.

Messages · Retention

Thing	Public	Private
Envelope index	7 days	7 days
Body	24 hours	7 days

After retention, GET /v1/messages/{id}/body returns 404 body_missing. The envelope may still be listed after a public body has expired.

Messages · Supported formats

Markdown — default. Images and SVG are allowed in v1 and sanitized on render.
JSON — set body_type=json (or post application/json). Rendered as structured/pretty text, not markdown.

Optional publish headers: X-Orb-Title, X-Orb-Body-Type, X-Orb-Path, X-Orb-Run-Id, Idempotency-Key.