`vyges model`

A model/provider registry for the Vyges agentic layer. It names AI models and resolves their connection details (backend · endpoint · model id · tool-calling capability · local/cloud) so the model is a registered, swappable choice — the same thin-descriptor + resolve pattern as vyges pdk-store, applied to models.

This is the configuration used by Mode 2 — when vyges itself drives the tools with a model you choose. (In Mode 1, your AI IDE owns the model and no registration is needed.) Register a model, then drive the tools with vyges model run.

Local models come first

Vyges is model-agnostic, and local models are the primary path — the design data your agent reasons over never leaves your machine. Serve an open model on an OpenAI-compatible endpoint (ollama, llama.cpp-server, vLLM, TGI — each exposes /v1) and register it with --local:

vyges model add semikong --backend openai-compat \
      --endpoint http://127.0.0.1:11434/v1 --model semikong-8b-q4 --tool-calling json --local

vyges model check   semikong          # is the endpoint reachable?
vyges model resolve semikong endpoint # http://127.0.0.1:11434/v1

Cloud models — API keys and URLs

Cloud models (Anthropic, OpenAI, …) are fully supported and are often the easiest way to start when your organization already has a subscription or corporate agreement. Two things to configure: a key and, optionally, a base URL.

Keys are a reference, never the secret

--api-key stores an environment-variable reference (e.g. $ANTHROPIC_API_KEY) — not the key itself. The driver expands it from the environment at call time, so no secret ever lands in model.json (safe to commit ./.vyges/model.json to a repo). Export the real key in your shell or CI secret store:

export ANTHROPIC_API_KEY=sk-ant-…
export OPENAI_API_KEY=sk-…

Per provider

Anthropic (Claude) — the default endpoint is api.anthropic.com, so omit --endpoint:

vyges model add claude --backend anthropic --model claude-sonnet-5 \
      --api-key '$ANTHROPIC_API_KEY' --tool-calling native --cloud

Route Claude through a corporate gateway / Bedrock- or Vertex-style proxy that speaks the Anthropic Messages API by pointing --endpoint at its base URL (the driver appends /v1/messages; a full …/messages URL is used as-is):

vyges model add claude-gw --backend anthropic --endpoint https://claude-gw.corp.com \
      --model claude-sonnet-5 --api-key '$CLAUDE_GW_KEY' --tool-calling native --cloud

OpenAI:

vyges model add gpt --backend openai-compat --endpoint https://api.openai.com/v1 \
      --model gpt-4o --api-key '$OPENAI_API_KEY' --tool-calling native --cloud

Grok (xAI) — OpenAI-compatible, just a different base URL:

vyges model add grok --backend openai-compat --endpoint https://api.x.ai/v1 \
      --model grok-2 --api-key '$XAI_API_KEY' --tool-calling native --cloud

Azure OpenAI / a corporate OpenAI gateway — point --endpoint at your deployment base (the driver appends /chat/completions):

vyges model add azure --backend openai-compat \
      --endpoint https://my-resource.openai.azure.com/openai/deployments/gpt4o \
      --model gpt-4o --api-key '$AZURE_OPENAI_KEY' --tool-calling native --cloud

Per-invocation / CI override

Override any model inline — without editing model.json — with a VYGES_MODEL_<NAME> env var holding a JSON object (handy in CI, where the endpoint/key vary per environment):

export VYGES_MODEL_GROK='{"backend":"openai-compat","endpoint":"https://api.x.ai/v1","model":"grok-2","api_key":"$XAI_API_KEY","local":false}'

Drive the tools (Mode 2)

Once a model is registered, run a task — vyges presents the installed vyges mcp tools to the model and runs the reason → tool-call → observe loop until the model signals done:

vyges model run semikong "check DRC on block1.gds with the sky130 deck and report the count"

Point it at a local model and the design data your agent reasons over never leaves your machine. (v1 uses JSON tool-calling and passthrough tool arguments; native provider tool-calling and finer controls are refinements.)

Commands

vyges model list                     list registered models
vyges model add <name> …             register into ~/.vyges/model.json
vyges model resolve <name> <key>     print one field (endpoint | model | tool_calling | local | …)
vyges model check <name>             report reachability of the model endpoint
vyges model run <name> "<task>"      drive the vyges mcp tools with the model (Mode 2)

`model.json`

Registrations live in a models map. Resolution order (first hit wins), mirroring tools.json:

env VYGES_MODEL_<NAME> — a JSON object (per-invocation / CI override)
project ./.vyges/model.json — a repo pins its model
user ~/.vyges/model.json — the host default

Two backends cover every provider: openai-compat (OpenAI, Grok/xAI, and OSS servers — ollama, llama.cpp-server, vLLM, TGI) and anthropic (Claude native).

{
  "$schema": "https://vyges.com/schema/v1/model.schema.json",
  "models": {
    "semikong": { "backend": "openai-compat", "endpoint": "http://127.0.0.1:11434/v1",
                  "model": "semikong-8b-q4", "tool_calling": "json", "local": true },
    "claude":   { "backend": "anthropic", "model": "claude-sonnet-5", "api_key": "$ANTHROPIC_API_KEY",
                  "tool_calling": "native", "local": false, "egress": "metadata-only" }
  }
}

Local vs cloud — and data egress

Mark each model --local or --cloud so it is explicit which models can see your design data. Local is the recommended default: the data your agent reasons over never leaves the machine — the same local-first trust model as the rest of the CLI.

For a cloud model the data leaves your boundary, so govern which models are allowed. Vyges is deliberately not a data-loss / egress firewall: local models keep data on the machine by construction, and for cloud models you enforce with your organization’s existing egress controls (proxy / CASB / DLP). Vyges records which model each call used; it does not claim to prevent leakage.

Keyboard shortcuts

Vyges