Models & Credentials

Every harness needs a model to run and credentials to reach it. You declare the model in your agent YAML, and Goalrail manages the credentials that authenticate to each provider.

Choose a model

Declare the model in your agent YAML:

executor:
  harness: claude-sdk
  model: claude-sonnet-4-6

Override it at runtime without editing the file:

goalrail run agent.yaml --model claude-sonnet-4-6

Switch models mid-session

Use the /model command inside any running session to switch models on the fly. The agent keeps its conversation history and tool state – only the underlying model changes.

Credentials

Goalrail needs credentials to talk to a model provider.

goalrail setup

The setup wizard walks you through adding a credential, setting a default, or removing one. It also auto-detects credentials already on your machine (API keys in environment variables, logged-in CLIs, and local servers) so you can confirm them with one tap.

Credential types

API key

Get a key from your provider's dashboard and add it via goalrail setup. Supported providers:

Provider	Key source
Anthropic	console.anthropic.com
OpenAI	platform.openai.com
OpenRouter	openrouter.ai
Groq	console.groq.com
DeepSeek	platform.deepseek.com
xAI	console.x.ai
Mistral	console.mistral.ai
Together AI	api.together.xyz
Fireworks AI	fireworks.ai

Subscription

If you have a Claude Pro/Max or ChatGPT Plus/Pro plan, Goalrail can use your existing CLI login. No API key needed. Just make sure you're logged in:

claude auth login    # for Claude Pro/Max
codex login          # for ChatGPT

goalrail setup auto-detects an active CLI login and offers it as a one-tap option.

Gateway

Goalrail works with any OpenAI-compatible or Anthropic-compatible gateway:

MLflow AI Gateway

OpenRouter

LiteLLM

Portkey

Helicone

Cloudflare AI Gateway

Kong AI Gateway

Vercel AI Gateway

Azure OpenAI

Ollama

LM Studio

vLLM

LocalAI

TGI (Hugging Face)

GPT4All

goalrail setup asks for a base URL and a key. The base URL differs depending on the agent: