AI Providers

mashin is provider-agnostic. Reasoning steps (ask) work with any supported provider. You choose the provider; mashin handles the governance.

Quick Setup

Set one environment variable. mashin auto-discovers available models.

# Pick one (or several)
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export GOOGLE_API_KEY="AIza..."

That’s it. Your machines can now run reasoning steps. mashin automatically selects the best model for each tier (fast, standard, capable) from whichever providers have keys configured.

Supported Providers

Direct Providers

These connect directly to the provider’s API.

Provider	Environment Variable	Free Tier	Best For
Anthropic	ANTHROPIC_API_KEY	No	Claude models. Strongest reasoning.
OpenAI	OPENAI_API_KEY	No	GPT models. Broad ecosystem.
Google AI Studio	GOOGLE_API_KEY	Yes (rate-limited)	Gemini models. Free for prototyping.
Groq	GROQ_API_KEY	Yes (rate-limited)	Fastest inference. Great for high-throughput.
xAI	XAI_API_KEY	No	Grok models.
DeepSeek	DEEPSEEK_API_KEY	No	DeepSeek reasoning models. Very cost-effective.
Mistral	MISTRAL_API_KEY	No	Mistral models. Strong for European deployments.

Aggregators

Route to multiple providers through a single API key.

Provider	Environment Variable	Free Tier	Best For
OpenRouter	OPENROUTER_API_KEY	Yes (select models)	One key, many providers. Free model access.
Together AI	TOGETHER_API_KEY	No	Open-source model hosting.

Enterprise / Cloud

For organizations with existing cloud infrastructure.

Provider	Environment Variables	Best For
Azure OpenAI	AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_KEY	Enterprise compliance, data residency.
AWS Bedrock	AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION	AWS-native deployments.
Google Vertex AI	VERTEX_PROJECT_ID, VERTEX_API_KEY	GCP-native deployments.

Local Models

No API key needed. Run models on your own hardware.

Provider	Setup	Best For
Ollama	Install Ollama, then ollama pull llama3.2:3b	Privacy, offline development, no costs.

Getting Started for Free

If you want to run reasoning steps without spending money, these are your options:

Option 1: Google AI Studio (recommended for beginners)

Free tier with generous rate limits. Sign up at aistudio.google.com, create an API key, and set it:

export GOOGLE_API_KEY="AIzaSy..."

Your machines will use Gemini models automatically.

Option 2: OpenRouter (access to many models)

Sign up at openrouter.ai. Some models are free. Set your key:

export OPENROUTER_API_KEY="sk-or-..."

Filter by free models in their dashboard to avoid charges.

Option 3: Groq (fastest inference)

Sign up at console.groq.com. Free tier with rate limits. Set your key:

export GROQ_API_KEY="gsk_..."

Groq runs open-source models on custom hardware. Response times are often under 200ms.

Option 4: Ollama (fully local, no account needed)

Install Ollama, pull a model, and go:

ollama pull llama3.2:3b

No API key needed. mashin detects Ollama automatically. Models run on your machine, completely offline.

Using a Provider in Your Machine

Specify the provider and model in your ask step:

machine classifier
  accepts
    text as text, required
  responds with
    category as text
  behaves
    ask classify, using: "anthropic:claude-sonnet-4-6"
      with task "Classify this text into a category.\n\nText: ${input.text}"
      returns
        category as text
  verifies
    test "classifies text"
      assuming classify {category: "general"}
      given {text: "hello"}
      expect {category: "general"}

The format is provider:model. Examples:

anthropic:claude-sonnet-4-6
openai:gpt-5.3-chat-latest
google:gemini-2.5-pro
groq:llama-3.3-70b-versatile
openrouter:anthropic/claude-sonnet-4-6
ollama:llama3.2:3b
deepseek:deepseek-v4-flash
mistral:mistral-large-latest

Model Tiers

If you don’t specify a model, mashin selects one based on the step’s tier:

Tier	Use Case	Example Selection
fast	High throughput, simple tasks	Claude Haiku, GPT-5.4 Mini, Gemma
standard	General reasoning (default)	Claude Sonnet, GPT-5.3, Gemini Pro
capable	Complex reasoning, escalation	Claude Opus, GPT-5.4, o3

mashin auto-discovers the latest models from each configured provider on startup. You always get the newest available model in each tier without changing your machine definitions.

Multiple Providers

Configure as many providers as you want. mashin uses them for:

• Fallback: If one provider is down, reasoning steps can route to another
• Cost optimization: Use cheaper providers for simple tasks, premium for complex ones
• Compliance: Route sensitive data through providers that meet your data residency requirements

# Production setup: primary + fallback
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."

# Development: free provider for iteration
export GOOGLE_API_KEY="AIzaSy..."

Testing Without Any Provider

Every machine can be tested without an API key. The assuming block provides deterministic mock values:

machine classifier
  accepts
    text as text, required
  responds with
    category as text
  behaves
    ask classify, using: "anthropic:claude-sonnet-4-6"
      with task "Classify this text.\n\nText: ${input.text}"
      returns
        category as text
  verifies
    test "classifies with a mocked model"
      assuming classify {category: "general"}
      given {text: "hello"}
      expect {category: "general"}

mashin test classifier.mashin
# Uses mock values. No API call. No key needed.

Tests are fast, free, and deterministic. Use them for CI, development iteration, and verifying machine structure before connecting a live provider.