Skip to content

Beta: these docs are still being updated. The next full update is on 18 November at 8 PM UTC. Docs in beta. Full update 18 Nov, 8 PM UTC.

Hoody.com

Open a Bot URL such as https://amber-falcon-river-k7m2q.hoody.bot in a browser and you get a chat page. Paste the key the Bot’s owner gave you and talk to the Bot. No app, no install and no Hoody account. If you own the Bot, you can also open the page from the Hub: open Bots, select the Bot, open Link and keys, and under Addresses choose Open the chat page in the Chat page row.

The page is the same for every Bot URL. It initially shows the address label and displays the Bot’s name after reading its status. It works only with a key. Fetching the page itself does not wake the Bot’s computer. Opening it with a saved key or a key in the link starts authenticated requests that can wake the computer.

By default, only GET / in a browser shows the page. Everything else gets the short text manual described in The keyless manual:

  • curl, scripts, HTTP libraries and AI agents
  • crawlers and anything else that calls itself a bot, except search engine indexers and link previews in chat apps, which see the page
  • a request with no browser User-Agent, or with an Accept header that prefers text/markdown

Add ?view=chat or ?view=text to the address to choose for yourself. /SKILL.md is always text.

Search engines are asked not to list the page or follow its links: every answer from a Bot URL, the page included, carries X-Robots-Tag: noindex, nofollow.

Paste the key in the Your key field and choose Use key. The page checks its shape first: a key is hbk_ followed by 43 letters and digits. When the owner left a note for your key, the page shows it under From the owner.

Where the key comes fromWhat happens
The Your key fieldKept in this tab only.
Remember on this device tickedKept in this browser until you choose Forget key.
A link ending in #key=hbk_…Read once. The page clears it from the address bar and uses it. If the browser does not allow that, the page does not use the key and asks you to enter it. The part after # never reaches a server.
A link ending in ?key=hbk_…Read once. The page clears it from the address bar and uses it. If the browser does not allow that, the page does not use the key and asks you to enter it. Either way the key has already reached the server with the address. Prefer #key=.

When a link carries a key both ways, the #key= one wins. The key shows masked. Open Key in the header to copy it or choose Forget key. The page sends it only to its own address, in an Authorization header. When the Bot does not accept a key (key_invalid), the page forgets it and shows Key refused: paste it again or ask the owner for a new one. A key that is paused or expired (key_disabled) is kept, and the page stops with This key is paused or expired. Ask the Bot’s owner.

To open the page with the key already in it, add #key= and the key to the address, as Connect explains under Share a link with the key. Anyone with that link can use your key, so send it only to yourself or to someone who may hold it.

The QR code button at the top shows this page’s address as a code to scan with a phone: Link only, or Link with my key, which adds #key= and your key so the phone opens the chat ready to use. Anyone who scans a code with your key can use it. Closing the code removes it from the page.

Type and send. On a computer, Enter sends and Shift+Enter adds a line. On a phone, Return adds a line and you tap Send.

The reply arrives in one piece when the Bot has finished, so the page shows Working… with a timer until then. Long work can take minutes. Stop waiting stops the page, not the Bot: the reply still lands in the shared log.

The chat shows every caller’s entries, not just your part: their messages, the Bot’s replies, reports from the agents it started, and notices. Each entry says who wrote it: You, another key by its name such as alice (key), Someone, Bot, Update or Notice. Your own messages show as You once the page has read your key’s name from the Bot. The tab keeps the last 200 entries, also across a reload, until you close it. Connect → This tab → Clear this tab empties the chat in this tab only; the entries stay in the shared log.

Shared log shows the Bot’s recent log entries, for every caller, and keeps itself up to date: the page follows the Bot’s live events, and where it cannot, checks every 15 seconds while the shared log is open or the Bot is at work, and every 60 seconds otherwise. Refresh reads it at once. Newer entries shows up when more entries wait.

Activity, at the top of the shared log, lists the agents the Bot started, each with a line such as working · since 3 min, done · reported 2 min ago, open · opened 5 min ago or, right after the Bot’s agent restarted, state unknown, plus how many approvals it waits on. When no agent is at work it says No delegates working. A chip in the header sums it up, such as 2 working or 1 waiting, amber while an approval waits; tap it to open Activity.

The log also says when an approval is waiting. The page has no approval buttons, but you can type your decision in the chat and name the agent whose approval you mean; the Bot can then answer that approval. A key holder can also answer by handle from an MCP client or the Hoody CLI, see Listen for events, and the owner can answer them in the agent.

Sometimes the page cannot tell whether the Bot got your message: the connection broke, the request timed out, or the Bot answered with an error after taking it. The page then says The Bot may still be working. Check the shared log before retrying.

  • Check shared log shows whether your message arrived and whether a reply is there.
  • Retry sends the same message with the same Idempotency-Key, so the Bot normally joins the first attempt instead of getting it twice.
  • Wait for the answer appears when the Bot said it is still working. It waits for the same reply and sends nothing new.
  • Send as a new message appears when the Bot refused the repeat as a conflict. It posts again.

After a reload, the transcript remains, but the retry key and recorded audio are gone. A message the reload cut off, or whose outcome was unclear, still offers Check shared log. A reply where the Bot was still working shows no button, so open Shared log in the header to check it.

Short refusals are handled for you. On rate_limited and concurrency_limit the page waits for Retry-After and retries up to 3 times (4 attempts in all). While the Bot is starting or briefly unavailable it waits 1 second, then longer, up to 30 seconds apart, and retries up to 7 times (8 attempts in all).

  • Talk records your voice and sends it to the Bot. A recording stops at 59 seconds and sends what you said so far; one shorter than half a second is not sent. The reply comes back as text, plus audio when the Bot can speak.
  • Read replies aloud reads each reply to a message you send from this tab, in pieces of up to 4096 characters. Replies that arrive through the shared log are not read out; Listen on a single reply reads just that one.

Voice needs the page over https://, a microphone and a recent browser. Nothing is recorded or sent until you tap. Voice requests use the Bot’s speech models, the agent’s speech models, or the default Hoody AI voices and count toward the Bot URL’s request limits. When the Bot cannot listen, the microphone shows crossed out, and tapping it says Voice isn’t set up for this Bot. Type your message instead. When the Bot cannot speak, Read replies aloud and Listen are hidden and replies come as text. Typing always works. There is no live voice conversation: each recording is one message.

Under Connect, This tab has Theme: Auto, Light and Dark. Auto follows your device. Your choice is remembered in this browser. Add ?theme=dark or ?theme=light (or #theme=) to a link to open the page in that theme.

Connect → Save as HTML downloads a small file named after the Bot, such as amber-falcon-river-k7m2q.html. Opened from disk, the saved file opens the chat in its browser tab. If automatic navigation is blocked, use the link in the file.

The key stays out of the file unless you tick Include my key (anyone with the file can then use it). A file with your key is your key: keep it where only you can open it.

Connect also lists the ways to call the Bot from your own tools: the Hoody CLI, the Hoody SDK, OpenAI-compatible and Anthropic-compatible clients, MCP, HTTP with curl, and coding agents such as Claude Code, Codex, opencode and pi. The page itself uses the chat door, the MCP server, live events and GET /v1/key for the owner’s note, the same paths described in Call a Bot URL.