# Documentation Page **Page:** kit/agent/bot-urls/security [Download Raw Markdown](./kit/agent/bot-urls/security.md) --- # Bot URL security 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. ## What a key holder can do 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 key holder who can answer approvals can let an agent run commands, edit files or push code on your computers, within what that agent is allowed to do. Give keys only to people and apps you trust with that. Set the agents' own permissions to what you are comfortable with when you are not watching. 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. What you and other callers type reaches every key holder exactly as written. If you paste a computer address, a file path, a password or a customer's details into the conversation, callers can read it. Keep private details out of the Bot's conversation. ## Keys - **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](/kit/agent/bot-urls/status/reference/#what-callers-see). A server-wide switch-off answers `bot_disabled` to everyone, and an unknown label or a deleted URL answers `bot_not_found`. See [Status](/kit/agent/bot-urls/status/#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](/kit/agent/bot-urls/create/#the-panic-button): it turns the URL off and revokes every key at once. A call already running finishes; an open [event stream](/kit/agent/bot-urls/calling/#live-events) 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. ## IPv4 only 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. ## Wrong-key protection 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](/kit/agent/bot-urls/errors/#wrong-keys). ## CORS 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. | `cors` | Effect | |---|---| | `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`. | | `false` | Disables 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. | Anything you put in a page's JavaScript can be read by everyone who opens the page. Keep keys on a server you control and call the Bot from there. Use browser access only for a page that asks the person in front of it for their own key, such as an internal tool for your team. 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 The [chat page](/kit/agent/bot-urls/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`. ## Transport 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. ## Request limits 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](/kit/agent/bot-urls/errors/#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. ## What to watch - Read the [access log](/kit/agent/bot-urls/status/#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. ## What's Next - [Create a URL and keys](/kit/agent/bot-urls/create/): pause, expiry, address lists and panic. - [Errors and limits](/kit/agent/bot-urls/errors/): the codes behind each refusal. - [Security](/concepts/security/): how Hoody protects your computers in general.