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

A Bot URL lets people outside your account steer one of your Bots. This page says what that gives them, what protects you, and where the limits of that protection are.

A key opens the same doors you use from an app on the Bot’s computer URL. With it, a caller can:

  • talk to the Bot in its one shared conversation, and read the Bot’s replies and its notes on its work
  • ask the Bot to start agents on your computers, which then do real work with the tools and permissions those agents have
  • answer the approval questions those agents ask, such as “may I run this command?”, the same way you can
  • use up your models, speech, and Hoody AI limits and credit

A caller cannot:

  • reach anything else in the computer: terminals, files, other kits or other Bots
  • manage the Bot, its keys or its URL
  • see other callers’ IP addresses, or your key notes

Hoody hides recognized identifiers in model-written replies, and the answers never carry them as fields. Text shaped like a Hoody internal id is replaced too, even when it is not one: a UUID, a 24-character hex string, or a task, helper or loop id shows as [hidden], and an open approval’s id shows as its handle. This is not a general privacy filter: project and computer names, Kit URLs, other paths and secrets can still appear. Keep private details out of the conversation. It does not judge what a message means, and messages from people are not filtered.

  • Shown once. Hoody keeps only a SHA-256 fingerprint of each secret and its first 12 characters (the prefix shown in the key table). Nobody, Hoody included, can show it to you again. A lost secret is rotated, not recovered.
  • One per person or app. Named keys let you see who called in the access log, pause or restrict each one to certain addresses, and revoke one without disturbing the others.
  • Never forwarded. The key is checked before the request reaches your computer and is removed from it. The Bot learns the key’s name and id and the caller’s IPv4 address, never the secret. Cookies and X-Hoody-* headers a caller sends are removed too, so a caller cannot pretend to be someone else.
  • Never logged. The access log records the key’s name and id, never the secret or its prefix, and never the query string where a ?key= would be.
  • Checked before the URL’s state is revealed. For the states you and Hoody set on the URL (Off, Frozen, Detached, a suspension), a request to an operation that needs a key gets key_invalid without a valid key, never bot_disabled. Keyless GET / and GET /SKILL.md still answer; see Status reference. A server-wide switch-off answers bot_disabled to everyone, and an unknown label or a deleted URL answers bot_not_found. See Status.

To take a key away for a while, pause it. To take it away for good, revoke it. When you do not know which key leaked, press panic: it turns the URL off and revokes every key at once. A call already running finishes; an open event stream stops sending events within about a minute after the change is applied, typically about 36 seconds. Work the Bot already started goes on until you stop it in the agent.

Bot URLs accept IPv4 only. A request over IPv6 is refused with ipv4_required, and an IPv6 entry in a key’s address list is refused when you save it, in every spelling, including IPv4-mapped forms such as ::ffff:203.0.113.7.

A key’s address list (ipv4_allow) is matched against the address the connection actually comes from. X-Forwarded-For and similar headers a caller sends are ignored, so they cannot be used to step around the list. Use it for keys held by servers with fixed addresses, such as an automation platform or your office network.

Guessing keys does not work: a secret holds about 256 random bits. Repeated wrong keys from one IPv4 address are slowed down and then blocked for 15 minutes (ip_blocked). See Wrong keys.

Browser access defaults to on when you create a URL through the API without specifying cors. A public link created alongside a new Bot in the Hub starts with browser access off. When enabled, a web page on any origin may call the Bot URL with a key, and read the answer and its error codes.

corsEffect
true (default)Answers, errors included, normally carry Access-Control-Allow-Origin with the calling page’s origin, Access-Control-Allow-Credentials: true and Vary: Origin. A browser preflight (OPTIONS) to one of the Bot’s paths gets 204 without needing a key; on any other path it gets path_not_allowed. Pages can read X-Hoody-Error-Code, X-Request-Id and Retry-After.
falseDisables CORS for normal Bot responses. A preflight to a supported path normally returns cors_disabled; an unsupported path normally returns path_not_allowed. Some generic errors can still carry CORS headers. Pages on other origins cannot read successful answers. The built-in chat page still works, and servers, scripts, SDKs and MCP clients are not affected.

Some errors can lack CORS headers with cors on, or carry them with cors off. The status and the error code are the same either way. These exceptions do not grant browser access to successful Bot responses.

Turn cors off when other websites should not call the Bot. It closes one way a key could be misused from a web page. To turn browser access off in the Hub, open the Bot’s Link and keys tab, choose Limits and websites, turn off Allow other websites (CORS), and choose Save. The built-in chat page still works.

The chat page at the Bot URL itself calls only its own address, so cors does not affect it. It holds no key until someone enters one, and it sends the key only to its own address, in a header. Keys handed around with the page can still leak:

  • A link with #key= never sends the key to a server, but anyone with the link can use the key. A link with ?key= sends the key to the server with the address.
  • Remember on this device keeps the key in that browser until someone chooses Forget key. Do not tick it on a shared computer.
  • A file saved with Include my key holds the key in plain text.

Other websites cannot frame the page by default. If the owner enables iframable, a website frame shows Open chat in a new tab and accepts no key or chat input. Older saved launchers that use a frame require iframable: true and a supported Chromium browser when opened from disk. Save a new HTML launcher to open the chat directly without enabling framing.

Search engines are asked to leave Bot URLs alone: every answer from a Bot URL, the chat page and the text manual included, carries X-Robots-Tag: noindex, nofollow, and the page also has a robots meta tag that says the same. There is no robots.txt rule, since a crawler that cannot fetch a page never sees its noindex.

Bot URLs work over HTTPS only. A request to http:// is refused and never redirected. Depending on which Hoody server receives it, the answer is https_required (426) or the generic bot_not_found (404), and neither says whether the name exists. A redirect would make the client send its key a second time in clear text. Always use https://. No answer from a Bot URL is cached on the way.

The URL has limits for each key and for the whole Bot, per minute and for calls at the same time, with defaults you can change. Both apply independently, and no capacity is set aside for any caller: one busy key can use up the whole Bot’s budget, especially if the per-key limit is set as high as the Bot limit. See Limits.

The per-key limit (limits.key_rpm) is one setting of the URL that applies to every key; there is no limit for a single key. The limits count requests, not money, and there is no spending cap yet. When one key’s use surprises you, pause that key; to slow every key down, lower the per-key limit.

  • Read the access log from time to time. Look for keys used from addresses you do not expect, runs of key_invalid or ip_not_allowed, and keys nobody should still be using.
  • Give keys an expiry date when the person needs access for a known time.
  • Revoke the keys of people who no longer need them. Revoking costs nothing; a new key takes seconds.