Model Aliasing

Model aliasing: swap providers without changing code.

Map app-facing names like "fast" and "smart" to real models underneath. Change the target at runtime — no code changes, no redeploys.

Set an alias in one call

# Create an alias
$ curl -X PUT localhost:4200/api/proxy/aliases \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -d '{"alias":"fast","target":"gpt-4o-mini"}'
{"alias":"fast","target":"gpt-4o-mini","created":"2026-03-27T..."}

# Now your app sends requests to "fast"
$ curl localhost:4200/v1/chat/completions \
  -d '{"model":"fast","messages":[{"role":"user","content":"hello"}]}'
→ routed to gpt-4o-mini

# Later, swap the target without touching app code
$ curl -X PUT localhost:4200/api/proxy/aliases \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -d '{"alias":"fast","target":"claude-haiku-4-5-20251001"}'
→ all "fast" requests now go to Claude Haiku
  

Or configure in YAML

# stockyard.yaml
model_alias:
  enabled: true
  aliases:
    fast: gpt-4o-mini
    smart: claude-sonnet-4-20250514
    cheap: deepseek-chat
    local: ollama/llama3
    

Aliases set via YAML load on startup. Aliases set via API persist in SQLite and survive restarts.

Why aliasing matters

Decouple app code from model versions

Your application requests "smart". You control what "smart" means. When a new model launches, update the alias — not every service that calls it.

A/B test models without deploys

Point "fast" at gpt-4o-mini for a week, then at claude-haiku the next. Compare cost and quality in Lookout traces. No code change either time.

Migrate providers gradually

Moving from OpenAI to Anthropic? Start by aliasing one low-risk model. Watch the traces. When you're confident, alias the rest.

Simplify multi-team coordination

Teams agree on alias names. The platform team controls what each alias resolves to. No more hardcoded model strings scattered across repos.

Runtime API

GET  /api/proxy/aliases          # list all aliases
PUT  /api/proxy/aliases          # create or update
DELETE /api/proxy/aliases?alias=fast # remove
GET  /api/proxy/aliases/stats     # usage counts per alias
    

All alias operations are audit-logged. Changes take effect immediately — no restart needed.

Starter presets

Common alias configurations to start with. Copy the YAML or set them through the API.

# stockyard.yaml — starter aliases
aliases:
  primary-chat: "gpt-4o"           # your main conversational model
  cheap-chat: "gpt-4o-mini"        # low-cost for simple tasks
  reasoning: "claude-sonnet-4-5"   # complex reasoning tasks
  fast-local: "llama-3.3-70b"      # local via Ollama or Groq
  embeddings: "text-embedding-3-small"
  

Your app calls primary-chat. When you want to try a new model, change one alias. No code change, no redeploy.

Name your models. Control the mapping.

Aliasing is free on every tier. Set aliases in YAML or through the API — they persist across restarts.

Install Stockyard

Aliasing Docs → Proxy-Only Setup → Ollama + Cloud Fallback →

Frequently Asked Questions

What is LLM model aliasing?

Model aliasing lets you define stable names for your app to use while mapping them to real provider models underneath. Your app calls 'fast' and Stockyard routes it to gpt-4o-mini, claude-haiku, or whatever you configure — changeable at runtime without redeploying.

Can I change aliases without restarting Stockyard?

Yes. Aliases can be created, updated, and deleted through the REST API at runtime. Changes take effect on the next request with no restart or redeploy needed.

Does aliasing work across different providers?

Yes. You can alias 'smart' to claude-sonnet-4-5 on Anthropic, then switch it to gpt-4o on OpenAI with one API call. Your application code never changes.

Is model aliasing free?

Yes. Aliasing is included in the free Community tier along with all 76 middleware modules.