Skip to content
Hoody Documentation
Hoody.com
Download Page (.md)

Hoody AI

Section titled “Hoody AI”

Hoody AI is a self-hosted gateway that runs on your own server and gives every container HTTP access to 300+ models from MiniMax, Qwen, DeepSeek, Llama, Mistral, Grok, and hundreds of others. Models from OpenAI, Anthropic, and Google are not part of the Hoody AI catalog; to use those, bring your own key (see “Bring your own provider” below).

Containers authenticate with container-X. The API is OpenAI-compatible, so any library or tool that speaks OpenAI’s format works against it unchanged: the OpenAI SDKs, LangChain, hoody-agent, Claude Code, Cline, Cursor. There is nothing to configure.

No provider API key lives in the container. A container-X token only works from your own infrastructure, so onboarding a freelancer, vibe coding, or running AI-generated code never puts a reusable key where that code can reach it.

Hoody AI adds a 5% markup on model provider costs. See Models & Pricing for current per-model pricing and cost optimization.

Where the gateway runs

Section titled “Where the gateway runs”

Hoody AI is an AI gateway that runs on the host, your bare metal server, rather than inside a container.

Your Server
├── Hoody AI Gateway (Host Only)
│   ├── URL: https://ai.hoody.com/api/v1
│   ├── Credits: Your Hoody AI credits
│   └── Accessible: Only from containers on this server
│
└── Container 1, 2, 3...
    └── Auth: "container-1" (proves container identity)

Because the gateway process sits on your own machine, a request leaves your container, passes through that process, and goes out through the model routing upstream to the inference provider, with a 5% markup on the provider’s cost. No Hoody-operated platform server terminates your prompts. If you want the whole path under your own control, proxy to your own AI providers via hoody-exec.

How it works

Section titled “How it works”

1. Container identity token

Section titled “1. Container identity token”

When you create a container, it automatically gets access to Hoody AI via a container identity token:

API Key: container-{containerName}

Example: a container named dev-env gets the identity token container-dev-env. Containers created without a custom name are addressable by their numbered form (container-1, container-2, …); both the name-derived and numbered forms are accepted, and they identify the same container. Neither is an API key you can copy.

2. OpenAI-compatible clients

Section titled “2. OpenAI-compatible clients”

Hoody AI implements the OpenAI API format, so it works with:

  • Any OpenAI SDK (Python, Node.js, Go, etc.)
  • AI frameworks (LangChain, LlamaIndex, etc.)
  • AI coding tools (Cursor, Windsurf, Claude Code, Cline, Continue.dev)
  • hoody-agent (native integration for container orchestration)
Terminal window
# hoody-agent uses Hoody AI automatically. The AI provider
# (base URL, key, model) is configured on the session/agent,
# not passed per request. Just dispatch a turn:
curl -X POST "https://{project}-{container}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/{id}/prompt:sync" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Build a todo app"
  }'

3. Make an AI request

Section titled “3. Make an AI request”

Once your container is running, call Hoody AI directly:

import { HoodyClient } from 'hoody-sdk';


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


// List available AI models
const models = await client.api.ai.listModels();
console.log(models.data.models);


// For chat completions, call the AI gateway directly from your container:
const response = await fetch('https://ai.hoody.com/api/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer container-dev-env',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'minimax/minimax-m3',
    messages: [{ role: 'user', content: 'Hello!' }]
  })
});
const data = await response.json();
console.log(data.choices[0].message.content);

4. Default access for new containers

Section titled “4. Default access for new containers”

AI access is enabled by default for all containers. A container can start making AI requests with its container-X authentication token as soon as it is running.

Why Hoody AI

Section titled “Why Hoody AI”

Model catalog

Section titled “Model catalog”

One API reaches 300+ models from 15+ AI inference providers. Your server calls them through Hoody AI’s gateway and its model routing upstream, with a 5% markup on the provider’s cost.

Major inference providers:

  • MiniMax - MiniMax M-series models
  • Qwen (Alibaba) - Qwen 3 Max and the Qwen family
  • DeepSeek - DeepSeek V-series, DeepSeek Coder
  • Meta (via providers) - Llama 4, Llama 3.3 70B, Llama 3.1 405B
  • Mistral AI - Mistral Large, Mistral Medium, Mixtral
  • xAI - Grok 4, Grok Vision
  • Microsoft - Phi models
  • Amazon - Nova models
  • NVIDIA - Nemotron models
  • Cohere - Command R+, Command R, Embed models
  • Perplexity AI - Sonar Pro, Sonar models
  • Together AI - Hosting platform for open models
  • Fireworks AI - Optimized inference for open models
  • Other providers, listed in the live catalog

OpenAI, Anthropic, and Google models are excluded from the Hoody AI catalog: /api/v1/ai/models never returns them. To use those vendors, bring your own key (see below).

Models & Pricing lists every available model with its current pricing and provider-specific capabilities.

You hold no accounts with these providers and install none of their SDKs. The gateway is the only endpoint you call.

Bring your own provider

Section titled “Bring your own provider”

Hoody AI’s gateway is optional, and 75+ other options work directly. Set ANTHROPIC_API_KEY, OPENAI_API_KEY, or any other provider’s environment variable inside a container and call that provider straight from your code. Point hoody-agent, Cursor, or Cline at any OpenAI-compatible endpoint (a local Ollama, Azure OpenAI, Together AI, an enterprise proxy) and the rest of the stack runs unmodified. Swapping the active profile switches models mid-conversation. Two containers can run two providers at once, Claude in one and GPT-4o in the other, if you want to compare them. The same swap points a container at a Llama model you fine-tuned yourself. Moving between providers is a configuration change rather than a migration.

Terminal window
# Direct provider access. Set these in the container environment
ANTHROPIC_API_KEY=sk-ant-...   # Anthropic direct
OPENAI_API_KEY=sk-...          # OpenAI direct
OPENAI_BASE_URL=http://localhost:11434/v1  # Local Ollama


# Or route through Hoody AI for key-less container auth
# API key: container-{containerName}  → works from this server only

Container-native integration

Section titled “Container-native integration”

The gateway targets container-based workflows:

  • Every container gets AI access when it is created
  • Authentication uses the container-X form
  • hoody-agent and AI coding tools work against it without setup
  • There are no environment variables to manage
  • There are no credentials to rotate

Key isolation

Section titled “Key isolation”

Because authentication is restricted to the container:

  • No provider API key is stored in the container
  • Access follows the container’s lifecycle
  • A freelancer or contractor can work in the container without receiving a provider key
  • AI-generated code has no provider key to leak

Intercept and control AI

Section titled “Intercept and control AI”

Hoody AI requests are ordinary HTTP, so hoody-exec can sit in front of the gateway as a MITM (Man-In-The-Middle) proxy and rewrite them.

Deploy a MITM script once, then change the base URL in your AI client.

Without MITM: https://ai.hoody.com/api/v1
With MITM:    https://PROJECT_ID-CONTAINER_ID-exec-1.node-us.containers.hoody.com/api/v1


Switching is a URL change; the client code stays the same.

What the script can do from that position:

  • Tool call tampering - Intercept and modify AI tool calls (redirect file writes, block dangerous commands, modify paths)
  • Human-in-the-loop - Pause AI for approval on high-stakes operations (deployments, deletions, payments)
  • Agent cascades - Trigger other agent instances over HTTP to build multi-agent systems
  • Cost optimization - Compress prompts, cache responses, route to cheaper models (40-70% savings)
  • Context injection - Add your knowledge base, company policies, or codebase docs to the context automatically
  • Observability - Log every prompt, response, and decision for debugging and compliance

Sandbox every AI file operation in 30 lines:

// /api/ai-proxy.js in hoody-exec
// @mode worker


const response = await fetch('https://ai.hoody.com/api/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer container-1',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(req.body)
});


const data = await response.json();


// Intercept and redirect file operations to sandbox
if (data.choices[0].message.tool_calls) {
  data.choices[0].message.tool_calls.forEach(call => {
    if (call.function.name === 'write_file') {
      const args = JSON.parse(call.function.arguments);
      args.path = '/sandbox' + args.path;  // Force sandbox
      call.function.arguments = JSON.stringify(args);
    }
  });
}


return res.json(data);

Every write_file path the model produces is rewritten under /sandbox before the response reaches the client, so the model can write wherever it likes and still land inside the sandbox.

Intercept & Control AI → covers tool call interception, agent cascade orchestration, human-in-the-loop workflows, stalling patterns, context injection, and cost optimization.

Use cases

Section titled “Use cases”

1. Safe freelancer onboarding

Section titled “1. Safe freelancer onboarding”

Give a contractor access to a container with its container-X API key. They can use Cursor, Windsurf, or Claude Code without ever seeing your real keys. Deleting the container at the end of the project revokes that access.

2. Consumer SaaS with AI

Section titled “2. Consumer SaaS with AI”

Build applications that use AI without embedding real API keys. A user with full source access has nothing to extract, because the key only works from your infrastructure.

3. Vibe-coded apps

Section titled “3. Vibe-coded apps”

Let AI generate entire applications. If the generated code logs or exfiltrates its API key, the container-X token it found is useless outside your server.

4. Multi-tenant AI access

Section titled “4. Multi-tenant AI access”

Each client gets their own container with isolated AI access, which you can enable or disable per client. Per-container usage tracking is not available yet; see the Security page.

5. Development environments

Section titled “5. Development environments”

Developers use AI coding assistants such as Cursor and Cline against the container-dev key while production uses container-prod, so the two environments never share a token.

Best practices

Section titled “Best practices”

Name containers descriptively

Section titled “Name containers descriptively”

Container names read back in your own code and config, though the gateway does not parse the suffix:

  • container-prod-frontend (clear purpose)
  • container-dev-alice (per-developer)
  • container-client-acme (per-client)

Use specific models

Section titled “Use specific models”

Specify exact models in AI requests to control costs:

{
  "model": "minimax/minimax-m3"
}

Use the cheapest model that clears the task and reserve the premium tiers for complex ones. Sort the live catalog on pricing.prompt to see what each one costs.

Check which containers have AI access

Section titled “Check which containers have AI access”

The ai field on each container records whether access is enabled:

Terminal window
# List all containers and their AI status
hoody containers list -o json | jq '.containers[] | {id, name, ai, status}'

Snapshot before AI-heavy operations

Section titled “Snapshot before AI-heavy operations”

Take a snapshot before letting AI generate large amounts of code, then restore it if the result is not what you wanted.

Useful questions

Section titled “Useful questions”

Can I use my own API keys or other AI gateways?

Section titled “Can I use my own API keys or other AI gateways?”

Yes. It is your infrastructure, so you can point containers at any AI provider or gateway:

  • Set environment variables in your containers and use providers directly (OpenAI, Anthropic, etc.)
  • Use other AI gateways, Together AI, or self-hosted models
  • Proxy through hoody-exec to any external service (see MITM section above)
  • Mix multiple providers with custom routing logic

Trade-offs to consider:

  • Using raw API keys in containers exposes them to container processes (a security risk if a container is compromised)
  • Hoody AI’s container-X authentication provides key isolation: the token only works from your infrastructure
  • With custom proxies via hoody-exec, you control everything but manage your own security

The server, the containers, and the choice of AI provider are all yours. Hoody AI is the default path, not a requirement.

What happens if I copy the container-X key elsewhere?

Section titled “What happens if I copy the container-X key elsewhere?”

It won’t work. The gateway resolves container identity from the request’s source address on your server, so a container-… token presented from anywhere else is rejected. There is nothing in the string itself to replay.

Can containers access each other’s AI requests?

Section titled “Can containers access each other’s AI requests?”

No. Each container’s AI authentication is isolated. Container A cannot see or intercept Container B’s AI traffic.

Does this work with local models (Ollama, LM Studio)?

Section titled “Does this work with local models (Ollama, LM Studio)?”

Hoody AI is for cloud providers. Run local models directly in a container and reach them over localhost.

What models are supported?

Section titled “What models are supported?”

See Models for the complete list. Hoody AI serves 300+ models from providers including MiniMax, Qwen, DeepSeek, Meta, Mistral, xAI, and more. OpenAI, Anthropic, and Google models are not in the catalog; bring your own key for those.

Troubleshooting

Section titled “Troubleshooting”

”Unauthorized” error

Section titled “”Unauthorized” error”

Problem: AI requests return 401 Unauthorized

Solutions:

  • Check the token starts with the container- prefix (the suffix is not parsed)
  • Confirm request is coming from the correct container
  • Ensure container is running (stopped containers can’t access AI)
  • Verify Hoody AI service is running on your server

”Model Not Found”

Section titled “”Model Not Found””

Problem: Requested model doesn’t exist

Solution: Model IDs pass through from Hoody AI’s upstream catalog, so the live list is authoritative. Pull it from your gateway and use the exact ID returned:

Terminal window
curl -s https://ai.hoody.com/api/v1/models -H "Authorization: Bearer container-$NAME" | jq -r '.data[].id'
{"model": "minimax/minimax-m3"}  // exact ID returned by /models
{"model": "minimax-m3"}          // short names are not valid IDs

Rate limit exceeded

Section titled “Rate limit exceeded”

Problem: Too many requests from container

Solutions:

  • Implement request throttling in application code
  • Check your Hoody AI credits balance
  • Distribute workload across multiple containers
  • Use more efficient models (a fast small model instead of a premium one)

Connection timeout

Section titled “Connection timeout”

Problem: AI requests timing out

Solutions:

  • Verify container has network access (firewall rules)
  • Check if Hoody AI service is running on host
  • Ensure container isn’t being rate-limited at network level
  • Try a simpler prompt to isolate the issue

What’s next

Section titled “What’s next”

Learn more:

Use AI in apps:

Related concepts: