Skip to content
habitat

Quickstart

A key, one curl, one verify. About five minutes.

Habitat is a public, story custody protocol. A write key opens a field of your own: append-only, sequestered, yours. No account. We can keep your field whole; we cannot read it as meaning.

1. Take a key

Press Take a write key at habitat.ooo, or mint one from a terminal:

curl -X POST https://habitat-api.fly.dev/api/writekey/mint

The response is your key card:

{
  "key": "hbk_<namespace>.<quota>.<expiry>.<signature>",
  "scope": "your field only",
  "minted": "2026-09-03 15:00 UTC",
  "expires": "2026-09-03 16:00 UTC",
  "quota": 5,
  "taste": "5 acts, 1 hour: enough to see a field form. When it expires, mint another; for a key that lasts, write to hello@habitat.ooo.",
  "fingerprint": "…",
  "custody": "this key writes to your field only; we can keep it whole, we cannot read it as meaning"
}

Keep the key. It is the only credential there is: no account, no email, no password. The signature inside it is the whole of its authority, and the server can verify it without keeping anything about you.

2. First act

Write the first line of your field. Habitat reads acts, someone doing something, so give it a sentence with an actor and a verb:

curl -X POST https://habitat-api.fly.dev/api/writekey/compose \
  -H "X-Write-Key: hbk_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"text": "I open my field and write the first line."}'

The act enters your field and nowhere else. The key addresses its own namespace only; nothing you send can reach another field, and no other key can reach yours.

Or hand the key to your agent instead, as MCP configuration:

{ "habitat": { "key": "hbk_YOUR_KEY_HERE" } }

3. Verify

Ask the field what shape your acts have made. Your field's session id is wk_ followed by the namespace segment of your key (the part between hbk_ and the first dot):

curl https://habitat-api.fly.dev/api/overlay/surface/wk_YOUR_NAMESPACE

The response is the overlay surface: which of the 17 dimensions carry signal, how mature the field is, where practice is dense and where it is just forming. That reading is computed from your field's own geometry and carries no one's interpretation, including ours.

The terms, plainly

  • Append-only. Acts enter; nothing is edited or erased behind you.
  • Scoped. A key writes to its own field only. This is enforced by the signature, not by a policy.
  • Quota and expiry ride inside the key and are printed on the card. The door key is a taste: five acts, one hour, enough to see a field form. When it expires, mint another, and when you want a standing key, write to hello@habitat.ooo.
  • Sequestered. No model reads meaning into your field. The overlay endpoints report geometry, never interpretation.

The full HTTP surface is generated from the code and gated against drift. Educational and noncommercial use is the Foundation's field; commercial licensing is a conversation: hello@habitat.ooo.