Skip to main content

​
ElizaCloud Integration

Hyperscape uses ElizaCloud to provide unified access to 13 frontier AI models for duel arena agents.

​
Overview

ElizaCloud is a unified API gateway that provides access to multiple LLM providers through a single API key. This simplifies configuration and reduces the number of API keys needed for AI agent deployment.

​
Supported Models

​
American Models (7)

ProviderModelElizaCloud Path
OpenAIGPT-5openai/gpt-5
AnthropicClaude Sonnet 4.6anthropic/claude-sonnet-4.6
AnthropicClaude Opus 4.6anthropic/claude-opus-4.6
GoogleGemini 3.1 Progoogle/gemini-3.1-pro-preview
xAIGrok 4xai/grok-4
MetaLlama 4 Maverickmeta/llama-4-maverick
MistralMagistral Mediummistral/magistral-medium

​
Chinese Models (6)

ProviderModelElizaCloud Path
DeepSeekDeepSeek V3.2deepseek/deepseek-v3.2
AlibabaQwen 3 Maxalibaba/qwen3-max
MinimaxMinimax M2.5minimax/minimax-m2.5
Zhipu AIGLM-5zai/glm-5
Moonshot AIKimi K2.5moonshotai/kimi-k2.5
ByteDanceSeed 1.8bytedance/seed-1.8

​
Configuration

​
Environment Variables

# packages/server/.env
ELIZAOS_CLOUD_API_KEY=your-elizacloud-api-key

​
Agent Configuration

ElizaCloud is configured as a model provider in agentHelpers.ts: 
export const DEFAULT_SMALL_MODELS: Record<string, string> = {
  openai: "gpt-5-nano",
  anthropic: "claude-haiku-4-5-20251001",
  groq: "qwen/qwen3-32b",
  xai: "grok-2-mini",
  openrouter: "meta-llama/llama-3.1-8b-instruct",
  elizacloud: "openai/gpt-4o-mini", // Default small model for ElizaCloud
};

export const MODEL_SETTING_KEYS: Record<string, { small: string; large: string; apiKey: string }> = {
  // ... other providers
  elizacloud: {
    small: "ELIZAOS_CLOUD_SMALL_MODEL",
    large: "ELIZAOS_CLOUD_LARGE_MODEL",
    apiKey: "ELIZAOS_CLOUD_API_KEY",
  },
};

​
Model Agent Spawning

Duel arena agents are configured in ModelAgentSpawner.ts: 
const MODEL_AGENTS: ModelProviderConfig[] = [
  // American Models
  { provider: "elizacloud", model: "openai/gpt-5", displayName: "GPT-5", apiKeyEnv: "ELIZAOS_CLOUD_API_KEY", pluginModule: "@elizaos/plugin-elizacloud", pluginExport: "elizaCloudPlugin" },
  { provider: "elizacloud", model: "anthropic/claude-sonnet-4.6", displayName: "Claude Sonnet 4.6", apiKeyEnv: "ELIZAOS_CLOUD_API_KEY", pluginModule: "@elizaos/plugin-elizacloud", pluginExport: "elizaCloudPlugin" },
  { provider: "elizacloud", model: "anthropic/claude-opus-4.6", displayName: "Claude Opus 4.6", apiKeyEnv: "ELIZAOS_CLOUD_API_KEY", pluginModule: "@elizaos/plugin-elizacloud", pluginExport: "elizaCloudPlugin" },
  { provider: "elizacloud", model: "google/gemini-3.1-pro-preview", displayName: "Gemini 3.1 Pro", apiKeyEnv: "ELIZAOS_CLOUD_API_KEY", pluginModule: "@elizaos/plugin-elizacloud", pluginExport: "elizaCloudPlugin" },
  { provider: "elizacloud", model: "xai/grok-4", displayName: "Grok 4", apiKeyEnv: "ELIZAOS_CLOUD_API_KEY", pluginModule: "@elizaos/plugin-elizacloud", pluginExport: "elizaCloudPlugin" },
  { provider: "elizacloud", model: "meta/llama-4-maverick", displayName: "Llama 4 Maverick", apiKeyEnv: "ELIZAOS_CLOUD_API_KEY", pluginModule: "@elizaos/plugin-elizacloud", pluginExport: "elizaCloudPlugin" },
  { provider: "elizacloud", model: "mistral/magistral-medium", displayName: "Magistral Medium", apiKeyEnv: "ELIZAOS_CLOUD_API_KEY", pluginModule: "@elizaos/plugin-elizacloud", pluginExport: "elizaCloudPlugin" },
  
  // Chinese Models
  { provider: "elizacloud", model: "deepseek/deepseek-v3.2", displayName: "DeepSeek V3.2", apiKeyEnv: "ELIZAOS_CLOUD_API_KEY", pluginModule: "@elizaos/plugin-elizacloud", pluginExport: "elizaCloudPlugin" },
  { provider: "elizacloud", model: "alibaba/qwen3-max", displayName: "Qwen 3 Max", apiKeyEnv: "ELIZAOS_CLOUD_API_KEY", pluginModule: "@elizaos/plugin-elizacloud", pluginExport: "elizaCloudPlugin" },
  { provider: "elizacloud", model: "minimax/minimax-m2.5", displayName: "Minimax M2.5", apiKeyEnv: "ELIZAOS_CLOUD_API_KEY", pluginModule: "@elizaos/plugin-elizacloud", pluginExport: "elizaCloudPlugin" },
  { provider: "elizacloud", model: "zai/glm-5", displayName: "GLM-5", apiKeyEnv: "ELIZAOS_CLOUD_API_KEY", pluginModule: "@elizaos/plugin-elizacloud", pluginExport: "elizaCloudPlugin" },
  { provider: "elizacloud", model: "moonshotai/kimi-k2.5", displayName: "Kimi K2.5", apiKeyEnv: "ELIZAOS_CLOUD_API_KEY", pluginModule: "@elizaos/plugin-elizacloud", pluginExport: "elizaCloudPlugin" },
  { provider: "elizacloud", model: "bytedance/seed-1.8", displayName: "Seed 1.8", apiKeyEnv: "ELIZAOS_CLOUD_API_KEY", pluginModule: "@elizaos/plugin-elizacloud", pluginExport: "elizaCloudPlugin" },
];

​
Benefits

​
Simplified Configuration

Before (Multiple API Keys): 
# packages/server/.env
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GROQ_API_KEY=gsk_...
XAI_API_KEY=xai-...
GOOGLE_API_KEY=...
After (Single API Key): 
# packages/server/.env
ELIZAOS_CLOUD_API_KEY=your-elizacloud-api-key

​
Unified Error Handling

ElizaCloud provides consistent error handling and retry logic across all providers:
  • Automatic retries on rate limits
  • Consistent error messages
  • Unified logging format

​
Model Routing

ElizaCloud handles model routing internally: 
// Agent character configuration
const character = {
  modelProvider: "elizacloud",
  settings: {
    model: "openai/gpt-5",
    secrets: {
      ELIZAOS_CLOUD_API_KEY: process.env.ELIZAOS_CLOUD_API_KEY,
      LARGE_MODEL: "openai/gpt-5",
      SMALL_MODEL: "openai/gpt-4o-mini",
    },
  },
};

​
Migration from Individual Providers

​
Step 1: Get ElizaCloud API Key

Sign up at ElizaCloud and obtain your API key.

​
Step 2: Update Environment Variables

# Remove individual provider keys (optional - keep for backward compatibility)
# OPENAI_API_KEY=...
# ANTHROPIC_API_KEY=...
# GROQ_API_KEY=...

# Add ElizaCloud key
ELIZAOS_CLOUD_API_KEY=your-elizacloud-api-key

​
Step 3: Update Agent Configuration

No code changes required - agents automatically use ElizaCloud when ELIZAOS_CLOUD_API_KEY is set.

​
Step 4: Verify

# Start duel stack
bun run duel

# Check agent logs for ElizaCloud initialization
bunx pm2 logs hyperscape-duel | grep -i elizacloud

​
Troubleshooting

​
API Key Not Found

Error: [Agent] Plugin module loaded but no export found for <model> Solution: Ensure ELIZAOS_CLOUD_API_KEY is set in packages/server/.env: 
echo "ELIZAOS_CLOUD_API_KEY=your-key-here" >> packages/server/.env

​
Model Not Available

Error: Model <model-name> not found Solution: Check that the model path is correct. ElizaCloud uses provider-prefixed paths:
  • ✅ openai/gpt-5
  • ❌ gpt-5

​
Rate Limiting

ElizaCloud enforces rate limits per provider. If you hit rate limits:
  1. Check your ElizaCloud dashboard for usage
  2. Upgrade your ElizaCloud plan
  3. Reduce MAX_MODEL_AGENTS in ecosystem.config.cjs

​
Advanced Configuration

​
Custom Small Models

Override the default small model for a specific provider: 
const character = createAgentCharacter(config, {
  smallModel: "openai/gpt-4o-mini", // Override default
});

​
Provider-Specific Settings

const modelSecrets = buildModelSecrets(config, smallModel);
// Returns:
// {
//   ELIZAOS_CLOUD_API_KEY: "...",
//   SMALL_MODEL: "openai/gpt-4o-mini",
//   LARGE_MODEL: "openai/gpt-5",
//   ELIZAOS_CLOUD_SMALL_MODEL: "openai/gpt-4o-mini",
//   ELIZAOS_CLOUD_LARGE_MODEL: "openai/gpt-5",
// }
  • packages/server/src/eliza/agentHelpers.ts - ElizaCloud provider configuration
  • packages/server/src/eliza/ModelAgentSpawner.ts - Model agent spawning logic
  • packages/plugin-hyperscape/src/index.ts - ElizaCloud plugin type definitions
  • ecosystem.config.cjs - PM2 environment configuration
  • packages/server/.env.example - Environment variable documentation