Bots
Talk to your Bots.
They run the agents.
A Bot is a long-lived assistant with one chat that keeps the whole conversation. Ask it for anything: it opens agents on your computers, follows their work and reports back what they did. Give it a .hoody.bot URL and share it with trusted people and AIs using named keys.
Your first Bot, chief, is there from the start. Hoody AI (free) is built in. Or sign in with ChatGPT. The Bot's helpers can use Claude Pro or Max through Claude Code when you allow them.
Fix the typo on My site and the Shop price, then sort new photos.
chiefone chat · older parts summarized · your limits
doneFix My site’s typo
asks youFix the Shop price
workingSort new photos
Each agent is a full Hoody Agent session on one of your computers.
Concretely
- Your first Bot
GET /api/ v1/ agent/ bots/ chief chiefis created on first use, so the list of Bots is never empty.- Where it runs
https://Bots run on the Hoody Agent ({p}-{c}-agent-1.{node}.computers.hoody.com/ api/ v1/ agent/ bots agent-1). Not the chat-app service at/api/bot/.
One message goes all the way. A report comes back.
You
from any of these
ReportDone. Shop is fixed.
Your computers
Your Bot
takes your message at once, reports back when it’s done
Agent
its helpers
Agent
its helpers
- My siteupdate
- Shopfix
- Photosback up
ExampleAll of it runs on your computers. Your Bot knows each one.
Concretely
- Its agents
GET /Each delegate is an ordinary session, read or attached with theapi/ v1/ agent/ bots/ chief/ delegates ?state=open /sessionsroutes. Open ones carrycapabilityandcurrent_step.- Its own live turn
GET /Reply text and thinking as they are written, tool calls, and the end of each turn.api/ v1/ agent/ sessions/ {session_id}/ stream session_idcomes fromGET /bots/{id}once the Bot has had its first message.
More: watch a full turn, one Bot at a time
You ask once. It hands out the work.
It replies, opens agents for the long parts, and comes back to you with their questions and their results.
You, 09:12
Fix the price typo on My site. And find out why Shop checkout got slow.
Chief, 09:12
On it. Opening two agents: one on My site for the fix, one on Shop to time checkout. I’ll report back.
Chief, 09:19
The My site agent fixed the typo and wants to run this. Allow it?
bash: ./publish.sh
You, 09:20
Yes, go.
Chief, 09:31
Done on My site: the fix is live. Checkout waits on one slow lookup; the Shop agent has a fix ready to try.
You, 09:12
Fix the price typo on My site. And find out why Shop checkout got slow.
Chief, 09:12
On it. Opening two agents: one on My site for the fix, one on Shop to time checkout. I’ll report back.
Chief, 09:19
The My site agent fixed the typo and wants to run this. Allow it?
bash: ./publish.sh
You, 09:20
Yes, go.
Chief, 09:31
Done on My site: the fix is live. Checkout waits on one slow lookup; the Shop agent has a fix ready to try.
Fix the price typo
workingasks youdoneon My sitemodel: Hoody AI (free)
now: editing the price pagewaits on: bash: ./publish.shreported back
Time the checkout
workingasks youdoneon Shopmodel: Hoody AI (free)
now: timing checkoutreported back
You, 10:02
Add the new autumn menu to Shop, and make sure the order tests still pass.
Shop keeper, 10:02
On it. One agent adds the menu, another runs the order tests. I’ll tell you when both are done.
Shop keeper, 10:14
The menu agent is ready to put the autumn menu live. Allow it?
bash: ./menu.sh
You, 10:15
Yes, publish it.
Shop keeper, 10:21
Done: the autumn menu is live on Shop, and all 48 order tests pass.
Add the autumn menu
workingasks youdoneon Shopmodel: Hoody AI (free)
now: adding 12 new disheswaits on: bash: ./menu.shreported back
Run the order tests
workingasks youdoneon Shopmodel: Hoody AI (free)
now: running 48 order testsreported back
You, 21:40
Photos is almost full. Clean up duplicates and check the backup.
Photo librarian, 21:40
On it. One agent looks for duplicates, another checks the backup. I’ll report back.
Photo librarian, 21:52
The cleanup agent found 1,240 duplicates. Delete them?
bash: ./clean.sh
You, 21:53
Yes, delete them.
Photo librarian, 22:05
Done: 1,240 duplicates gone, 18 GB free again. Last night’s backup is complete.
Remove duplicates
workingasks youdoneon Photosmodel: Hoody AI (free)
now: comparing photoswaits on: bash: ./clean.shreported back
Check the backup
workingasks youdoneon Photosmodel: Hoody AI (free)
now: reading the backupreported back
You, 08:03
Is My site up? Someone says the contact form is broken.
Site watcher, 08:03
Checking now. One agent tests the site, another looks at the form. I’ll report back.
Site watcher, 08:11
The form agent found the bug and has a fix. Ship it?
bash: ./publish.sh
You, 08:12
Yes, ship it.
Site watcher, 08:19
Done: My site is up, and the contact form works again. The form agent tested it after the fix.
Fix the contact form
workingasks youdoneon My sitemodel: Hoody AI (free)
now: reading form errorswaits on: bash: ./publish.shreported back
Check every page
workingasks youdoneon My sitemodel: Hoody AI (free)
now: opening 40 pagesreported back
You, 15:30
Which of three newsletter tools is cheapest for 5,000 readers?
Research buddy, 15:30
On it. Two agents read up on the tools. I’ll come back with one pick.
Research buddy, 15:41
The prices agent wants to save its notes on Shop. Allow it?
write: notes/tools.md
You, 15:42
Yes, save them.
Research buddy, 15:47
Done: tool B is the cheapest for 5,000 readers. The notes on Shop list all three prices.
Compare the prices
workingasks youdoneon Shopmodel: Hoody AI (free)
now: reading three price pageswaits on: write: notes/tools.mdreported back
Compare features
workingasks youdoneon Shopmodel: Hoody AI (free)
now: listing the featuresreported back
Concretely
- Your message
POST /Answersapi/ v1/ agent/ bots/ chief/ messages 202withmessage_id,stateandturn_id;state: queuedwhile the Bot is busy.- Its reply
GET /SSE: aapi/ v1/ agent/ bots/ chief/ stream stateframe, then onerowper log row; resume withLast-Event-ID.- Stop one agent
POST /Stops that agent's work at once, never the Bot.api/ v1/ agent/ bots/ chief/ delegates/ {sid}/ stop {"close": true}also closes its session.- Say it out loud
POST /A wav or mp3 recording is transcribed and posted as your message.api/ v1/ agent/ bots/ chief/ messages/ audio
Give your Bot a public URL. Connect trusted people, apps and AIs.
One URL, three ways in: as a model for apps and SDKs that take a base URL (OpenAI or Anthropic format), as an MCP server, or over plain HTTP from a script.
chief · Bot URL
https://<label>.hoody.bot 1In an app
Chat completions, responses and models. Only the last user message is posted; the app’s own system prompt and settings are left out.
Messages and models, on the URL without /v1. Only the last user message is posted; the app’s own system prompt and settings are left out.
Your Bot as an MCP server: JSON-RPC replies, no session to keep and no event stream.
Example Use a Bot as a model
Talks to your chief Bot like any AI model, from any app that speaks the OpenAI format.
Use my chief Bot as the model in my own app.
import OpenAI from 'openai';
const chief = new OpenAI({
baseURL: 'https://{p}-{c}-agent-1.{node}.computers.hoody.com/api/v1/agent/bots/global/chief/v1',
apiKey: 'any',
});
const res = await chief.chat.completions.create({
model: 'bot:global/chief',
messages: [{ role: 'user', content: 'Is the shop up?' }],
});import requests
r = requests.post(
"https://{p}-{c}-agent-1.{node}.computers.hoody.com/api/v1/agent/bots/global/chief/v1/chat/completions",
json={
"model": "bot:global/chief",
"messages": [{"role": "user", "content": "Is the shop up?"}],
},
)
print(r.json())BASE="https://{p}-{c}-agent-1.{node}.computers.hoody.com"
curl -X POST "$BASE/api/v1/agent/bots/global/chief/v1/chat/completions" \
-H "Content-Type: application/json" \
-d '{"model": "bot:global/chief", "messages": [{"role": "user", "content": "Is the shop up?"}]}'curl -X POST "https://{p}-{c}-agent-1.{node}.computers.hoody.com/api/v1/agent/bots/global/chief/v1/chat/completions" \
-H "Content-Type: application/json" \
-d '{"model": "bot:global/chief", "messages": [{"role": "user", "content": "Is the shop up?"}]}'import requests
r = requests.post(
"https://{p}-{c}-agent-1.{node}.computers.hoody.com/api/v1/agent/bots/global/chief/v1/chat/completions",
json={
"model": "bot:global/chief",
"messages": [{"role": "user", "content": "Is the shop up?"}],
},
)
print(r.json())https://{p}-{c}-curl-1.{node}.computers.hoody.com/api/v1/curl/request?url=https://{p}-{c}-agent-1.{node}.computers.hoody.com/api/v1/agent/bots/global/chief/v1/chat/completions&method=POST&json={"model":"bot:global/chief","messages":[{"role":"user","content":"Is%20the%20shop%20up?"}]}&response=transparent2From a script
Plain HTTP
POST /bots/ chief/ messages Hand it a task from a script, a cron job or another AI.
GET /bots/ chief/ stream Follow finished replies and agent events. The Bot's session stream shows reply text as it is written.
POST /bots/ chief/ delegates/ {sid}/ stop Stop one agent; the Bot keeps going.
Example Give a Bot a task
Asks your chief Bot to check that the shop is up.
Ask my chief Bot to check that the shop is up.
hoody -c {c} agent bots messages send \
--id chief \
--text "Check that the shop is up"import { HoodyClient } from 'hoody-sdk';
const hoody = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
const box = await hoody.withComputer('{c}');
const result = await box.agent.bots.sendMessage('chief', { text: 'Check that the shop is up' });
console.log(result.state);import requests
r = requests.post(
"https://{p}-{c}-agent-1.{node}.computers.hoody.com/api/v1/agent/bots/chief/messages",
json={"text": "Check that the shop is up"},
)
print(r.json())BASE="https://{p}-{c}-agent-1.{node}.computers.hoody.com"
curl -X POST "$BASE/api/v1/agent/bots/chief/messages" \
-H "Content-Type: application/json" \
-d '{"text": "Check that the shop is up"}'curl -X POST "https://{p}-{c}-agent-1.{node}.computers.hoody.com/api/v1/agent/bots/chief/messages" \
-H "Content-Type: application/json" \
-d '{"text": "Check that the shop is up"}'import requests
r = requests.post(
"https://{p}-{c}-agent-1.{node}.computers.hoody.com/api/v1/agent/bots/chief/messages",
json={"text": "Check that the shop is up"},
)
print(r.json())https://{p}-{c}-curl-1.{node}.computers.hoody.com/api/v1/curl/request?url=https://{p}-{c}-agent-1.{node}.computers.hoody.com/api/v1/agent/bots/chief/messages&method=POST&json={"text":"Check%20that%20the%20shop%20is%20up"}&response=transparent3Who gets in
Give each trusted person or app a named key. Pause it, set an expiry or IPv4 restriction, or revoke it separately.
Everyone with a key shares one conversation. Share only with people and AIs you trust.
Keep a Bot to one realm: its agents see only that realm’s computers.
Concretely
- Bot base
https://{p}-{c}-agent-1.{node}.computers.hoody.com/api/v1/agent/bots/{realm}/{bot}OpenAI uses<base>/v1, Anthropic the base, MCP<base>/mcp.{realm}isglobalor a 24-hex id.GET /bots/{id}lists them underurls. Shared Bot:https://<label>.hoody.bot/v1/chat/completionswith a Bearer key.- Post a message
curl -X POST "<agent>/api/v1/agent/bots/chief/messages" -H "Authorization: Bearer <token>" -d '{"text":"Ship it"}'At most 64 KiB of text; answers 202.- Stop one agent
POST /api/v1/agent/bots/chief/delegates/{sid}/stop {"close":true}Stops a delegate, never the Bot.
Plain English. That's the whole setup.
Type what your Bot must never do, in your own words. Save. Done.
- No syntax
- Every agent gets it
- Risky work is checked before it starts
chief · guardrailsExample
Concretely
- Replace guardrails
PUT /api/v1/agent/bots/chief/guardrails {"guardrails":"Never push to main."}One text field; the Bot gets each line marked[guardrails updated]before its next message.- How strict
"guardrail_check": "strict"strict(default),lenientoroff. docs / api / agent / bots ↗
Concretely
- Post from anywhere
POST /api/v1/agent/bots/chief/messages {"text":"Is staging up?"}Answers 202;queuedwhile the Bot is busy. Add anIdempotency-Keyto retry safely.- Resume the stream
GET /api/v1/agent/bots/chief/stream?since=154Server-Sent Events; each row frame’s id is itsseq, soLast-Event-IDresumes by itself.- Voice doors
…/bots/{id}/voice · …/bots/{id}/realtimeOne live voice connection per Bot at a time;takeover=truereplaces it. docs / api / agent / bots ↗
More: the log
Four devices, a phone, a laptop, a terminal and an AI app, are open on the same Bot. The phone and the laptop send at the same moment, 22:31; the messages land as #152, then #153, and the Bot replies as #154. Every device sees the same order. Older turns fold into a short summary, rows #1 to #120; the newest turns, #121 to #154, stay word for word. The full log keeps every row.
Every device, one conversation. Your phone, laptop, terminal and AI apps are open on the same Bot at once, and every device sees the same order. Key holders share it too, so share only with people you trust.
Every message gets the next number. Two sent at the same moment land as #152, then #153. One sent while the Bot is busy waits for its next turn.
It never runs out of room. When the model’s window fills, older turns fold into a short summary, the newest stay word for word, and the Bot carries on. The log keeps every row; forget moves them to the archive.
What a row holds
seq, at, role (user, bot, event or system) and text. It can also have session_id. The log pages by seq; the stream sends each new row as it is written.Switching models
Memory your agents keep
Concretely
- Read the log
GET /api/v1/agent/bots/chief/logRows in order, paged byseq.- Follow it
GET /api/v1/agent/bots/chief/streamAstateframe, then rows; a cursor moved to the archive answerslagged.- Forget
POST /api/v1/agent/bots/chief/forgetRead it later withGET …/archive; delete it withPOST …/purge.
More: hooks
Hook in. Your script sees the call first and the answer last.
A hook sends matching HTTP calls to the Bot, or most other services on your computers, through one of your Exec scripts first. WebSocket upgrades on a matching path are refused, so keep paths like the Bot voice doors outside the match. On the way in, it can watch, check, change, answer or block them. On the way out, it can read the answer and change it before the caller gets it. Nothing to patch.
InOn the way in
WatchLog who called and what, then pass it on.See scriptHide script
Rule:
POST /api/v1/agent/bots/*→/bot-auditmodule.exports = async function (req, res, metadata) { if (!metadata.hook) { res.writeHead(404); return res.end(); } const ip = req.headers['x-real-ip']; console.log(metadata.hook.auditId, metadata.hook.origPath, ip); await metadata.hook.forward(req, res); };The script sees the real client IP. Called without a hook,
metadata.hookis empty, so it answers 404.forward()passes the call on to the Bot as it was.CheckLet only signed-in people through. A rate limit sits in the same spot.See scriptHide script
Rule:
any method except OPTIONS /api/v1/agent/bots/*→/identity-gatemodule.exports = async function (req, res, metadata) { if (!metadata.hook) { res.writeHead(404); return res.end(); } const user = verifyClaim( req.headers['x-hoody-claim']); if (!user) { res.writeHead(401); return res.end(); } await metadata.hook.forward(req, res, { headers: { 'x-hoody-claim': null, 'x-hoody-user': user.username, } }); };verifyClaimchecks a Hoody login claim signed with ED25519; the docs have the full script. Anyone without one gets a 401 and never reaches the Bot. This rule would also refuse the WebSocket voice paths; narrow it to leave them out.- ChangeRewrite the method, path, headers or body before it arrives.
- BlockTurn away uploads that fail a virus scan, or calls over your limit.
AnswerReply yourself, like “Back soon”, and the Bot never sees the call.See scriptHide script
Rule:
POST /api/v1/agent/bots/*→/bot-gatemodule.exports = async function (req, res, metadata) { if (!metadata.hook) { res.writeHead(404); return res.end(); } if (process.env.MAINTENANCE) { res.writeHead(503); return res.end('Back soon'); } await metadata.hook.forward(req, res, { headers: { cookie: null } }); };A reply the script sends never reaches the Bot.
forward()can also change the method, path, headers or body; a header set tonullis removed.
OutOn the way out
- Read the answerSee its status, headers and body before the caller does.
RewriteSend the answer on as it is, or send your own.See scriptHide script
Rule:
any method except OPTIONS /api/v1/agent/bots/*→/bot-answermodule.exports = async function (req, res, metadata) { if (!metadata.hook) { res.writeHead(404); return res.end(); } const up = await metadata.hook.fetchUpstream(req); if (up.status === 401) { res.writeHead(401); return res.end('Please sign in again'); } res.setHeader('x-hoody-hook-audit', metadata.hook.auditId); await metadata.hook.pipeResponse(up, res, { method: req.method }); };fetchUpstream()gets the Bot’s answer without sending it, so the script reads it first;pipeResponse()sends it on. A streamed answer ends at the hook’s time limit, 30000 ms at most.- Clean headersStrip private headers from answers, add a CSP.
Each hook has a time limit, 500 ms by default. If the script fails or runs out of time, the call stops there. docs / proxy / hooks ↗
Concretely
- Add a hook
POST /api/v1/computers/{id}/proxy/hooks/agent · If-Match: file:v<N> {"match":{"method":["POST"],"path":"/api/v1/agent/bots/*"},"script":{"path":"/bot-audit"},"timeout":500}The server gives the hook its id. Rules run in order and the first match wins.- Read the version
GET /api/v1/computers/{id}/proxy/hooks/agentEvery change to hooks needsIf-Match: file:v<N>with the current version.- The script
POST /api/v1/exec/scripts/write {"path":"bot-audit.js","content":"module.exports = async function (req, res, metadata) { … }"}The script body here is the shape only: put your audit code in place of{ … }.script.pathnames a script in your own hoody-exec. Write it on your exec link;/bot-auditservesbot-audit.js. docs / api / exec / script-management ↗
Start free, in one line.
Free to start with no card: Hoody AI is built in, and the AI you already use works too.
Works in ChatGPT, Claude or any AI that can fetch a page. Copy it and paste it in.
- Terminal
ssh hoody.comAny machine with an ssh client, in an interactive terminal. Nothing to install.- docs / kit / agent
- Skill
npx skills add https://hoody.com/SKILLS/SKILL.mdnpx skills add HoodyNetwork/hoody-sdkThe second one adds every docs page on disk, for offline use.- docs / foundation / agent-skill-bundle
- CLI
npm install -g hoody-sdkcurl -fsSL https://install.hoody.com | shThe second one is for Linux and macOS. Without installing:npx hoody-sdk <command>- docs / foundation / cli
- SDK
npm install hoody-sdkTypeScript. Node.js 20.19 or newer, Bun, Deno.- docs / getting-started / quickstart
- HTTP API
curl -H "Authorization: Bearer <token>" https://api.hoody.com/api/v1/computers/- docs / api / authentication
- Browser SDK
<script src="https://cdn.jsdelivr.net/npm/hoody-sdk/dist/hoody-sdk.browser.min.js"></script>Exposeswindow.HoodySDK. Pin a version for production, and give pages short-lived scoped tokens.- docs / getting-started / quickstart