Skip to content
Magic Shell

AI Providers

Magic Shell supports multiple AI providers, including OpenCode Zen, OpenRouter, Vercel AI Gateway, Cloudflare AI Gateway, Workers AI, and custom models for local or remote endpoints. All providers are equal options — pick the one that fits your workflow, budget, and existing infrastructure.

The full per-provider model catalog — names, IDs, categories, cost, and context length — is generated from src/lib/models.ts so it can’t drift from the CLI. See Models → for the live list. Cost legend:

  • Free — no-cost model (may be time-limited)
  • Lower-cost — open-weight, flash, or haiku-class model
  • Premium — flagship or high-capability model

Model Equivalents Across Providers

Section titled “Model Equivalents Across Providers”

Flagship models are available on multiple providers. Use this table to find the equivalent model ID on your preferred provider. Empty cells (—) mean that provider does not offer the model.

Model family OpenCode Zen OpenRouter Vercel AI Gateway Cloudflare AI Gateway Workers AI
GPT 5.5 gpt-5.5 openai/gpt-5.5 openai/gpt-5.5 openai/gpt-5.5 —
GPT 5.5 Pro gpt-5.5-pro openai/gpt-5.5-pro openai/gpt-5.5-pro — —
Claude Sonnet 4.6 claude-sonnet-4-6 anthropic/claude-sonnet-4.6 anthropic/claude-sonnet-4.6 anthropic/claude-sonnet-4-6 —
Claude Opus 4.8 claude-opus-4-8 anthropic/claude-opus-4.8 anthropic/claude-opus-4.8 anthropic/claude-opus-4-8 —
Claude Haiku 4.5 claude-haiku-4-5 — — — —
Gemini 3.5 Flash gemini-3.5-flash — — — —
DeepSeek V4 Flash deepseek-v4-flash deepseek/deepseek-v4-flash — — —
DeepSeek V4 Pro deepseek-v4-pro deepseek/deepseek-v4-pro — — —
GLM 5.2 glm-5.2 z-ai/glm-5.2 — — —
Kimi K2.6 kimi-k2.6 moonshotai/kimi-k2.6 — — —
Kimi K2.7 Code — moonshotai/kimi-k2.7-code — — —
Qwen 3.7 Max qwen3.7-max qwen/qwen3.7-max — — —
MiMo V2.5 mimo-v2.5 xiaomi/mimo-v2.5 — — —
Llama 3.3 70B Fast — — — workers-ai/@cf/meta/llama-3.3-70b-instruct-fp8-fast @cf/meta/llama-3.3-70b-instruct-fp8-fast
Llama 3.1 8B — — — — @cf/meta/llama-3.1-8b-instruct
GPT OSS 120B — — — — @cf/openai/gpt-oss-120b

OpenCode Zen

Section titled “OpenCode Zen”

OpenCode Zen provides curated models optimized for coding tasks, including several free models (some are time-limited).

Get an API Key

Section titled “Get an API Key”
  1. Visit opencode.ai/auth
  2. Sign up or log in
  3. Copy your API key
  4. Run msh --setup and paste it

OpenRouter

Section titled “OpenRouter”

OpenRouter provides access to models from many providers through a single API, including open-weight value options not available on the other gateways.

Get an API Key

Section titled “Get an API Key”
  1. Visit openrouter.ai/keys
  2. Create an account
  3. Generate a new API key
  4. Run msh --setup and select OpenRouter

Vercel AI Gateway

Section titled “Vercel AI Gateway”

Vercel AI Gateway routes requests to multiple model providers through a single Vercel-managed endpoint.

Get an API Key

Section titled “Get an API Key”
  1. Visit your Vercel dashboard
  2. Open the AI Gateway settings and create a token
  3. Run msh --setup and select Vercel AI Gateway

Cloudflare AI Gateway

Section titled “Cloudflare AI Gateway”

Cloudflare AI Gateway routes requests to upstream providers (OpenAI, Anthropic, Workers AI) through Cloudflare with caching, rate limiting, and observability. Requires a Cloudflare account ID and gateway ID.

Get an API Key

Section titled “Get an API Key”
  1. Visit dash.cloudflare.com
  2. Note your Account ID (found on the Cloudflare dashboard sidebar)
  3. Create an AI Gateway and note its Gateway ID (defaults to default)
  4. Create an API token with AI Gateway permissions
  5. Run msh --setup and select Cloudflare AI Gateway, then set your account ID and gateway ID

Cloudflare Workers AI

Section titled “Cloudflare Workers AI”

Workers AI runs open models directly on Cloudflare’s network — no upstream provider required. Requires a Cloudflare account ID.

Get an API Key

Section titled “Get an API Key”
  1. Visit dash.cloudflare.com
  2. Note your Account ID (found on the Cloudflare dashboard sidebar)
  3. Create an API token with Workers AI permissions
  4. Run msh --setup and select Workers AI, then set your account ID

Switching Providers

Section titled “Switching Providers”

Via CLI

Section titled “Via CLI”
Terminal window
# Switch to OpenRouter
msh --provider openrouter


# Switch to OpenCode Zen
msh --provider opencode-zen


# Switch to Vercel AI Gateway
msh --provider vercel-ai-gateway


# Switch to Cloudflare AI Gateway
msh --provider cloudflare-ai-gateway


# Switch to Workers AI
msh --provider workers-ai

Via TUI

Section titled “Via TUI”

Press Ctrl+P and choose Switch Provider, or type /providers. Both routes open the same provider picker.

Switching Models

Section titled “Switching Models”

Via CLI

Section titled “Via CLI”
Terminal window
# List available models
msh --models


# Set default model
msh --model deepseek-v4-flash-free

Via TUI

Section titled “Via TUI”

Press Ctrl+X M, choose Change Model from Ctrl+P, or type /models. All routes open the same model picker.

Environment Variables

Section titled “Environment Variables”

Set your API keys via environment variables:

Terminal window
# OpenCode Zen
export OPENCODE_ZEN_API_KEY="your-key"


# OpenRouter
export OPENROUTER_API_KEY="your-key"


# Vercel AI Gateway
export AI_GATEWAY_API_KEY="your-key"


# Cloudflare AI Gateway
export CLOUDFLARE_AI_GATEWAY_API_KEY="your-gateway-token"
export CLOUDFLARE_ACCOUNT_ID="your-account-id"
export CLOUDFLARE_AI_GATEWAY_ID="your-gateway-id"


# Cloudflare Workers AI
export CLOUDFLARE_API_TOKEN="your-token"
export CLOUDFLARE_ACCOUNT_ID="your-account-id"

Keys stored in the system keychain (via msh --setup) take precedence over environment variables.

Custom Models

Section titled “Custom Models”

Magic Shell supports custom models for local or remote OpenAI-compatible endpoints. This is perfect for:

  • LM Studio - Run models locally on your machine
  • Ollama - Local model management
  • Self-hosted APIs - Your own OpenAI-compatible endpoints
  • Third-party services - Any OpenAI-compatible API

Adding a Custom Model

Section titled “Adding a Custom Model”
Terminal window
# Interactive setup wizard
msh --add-model

You’ll be prompted for:

  • Model ID: A unique identifier (e.g., my-local-llama)
  • Display name: Human-readable name (e.g., Local Llama 3.2)
  • API model ID: The model identifier sent to the API (e.g., llama-3.2-3b)
  • Base URL: The API endpoint (e.g., http://localhost:1234/v1)
  • API key: Optional, stored securely in your system keychain
  • Category: fast, smart, or reasoning

Managing Custom Models

Section titled “Managing Custom Models”
Terminal window
# List all custom models
msh --list-custom


# Set a custom model as default
msh --model my-local-llama


# Remove a custom model
msh --remove-model my-local-llama

Example: LM Studio

Section titled “Example: LM Studio”
Terminal window
# Start LM Studio and load a model
# Then add it to Magic Shell:
msh --add-model


# Model ID: llama-3.2-local
# Display name: Local Llama 3.2
# API model ID: llama-3.2-3b
# Base URL: http://localhost:1234/v1
# API key: (leave empty for LM Studio)
# Category: smart


# Use it
msh --model llama-3.2-local "find all large files"

Custom model API keys are securely stored in your system keychain, just like provider API keys.