Access Claude Opus 4.5, Sonnet 4.5, GPT-5, Gemini, DeepSeek, and 500+ AI models through Puter.com OAuth. Includes 400+ FREE OpenRouter models. No API keys needed - free tier available with undocumented limits.

Enable OpenCode to authenticate with Puter.com via OAuth, giving you access to premium AI models through your Puter account. Ideal for app developers using the "User-Pays" model where each user covers their own AI costs.

• Claude Opus 4.5, Sonnet 4.5 - Best coding AI models
• GPT-5.2, o3-mini, o4-mini - OpenAI's latest models
• Gemini 2.5 Pro - 1M context window
• DeepSeek R1 - Advanced reasoning model
• 500+ More Models - Mistral, Llama, Grok, and more
• 400+ FREE OpenRouter Models - Including MiMo-V2-Flash (#1 on SWE-bench), Qwen3 Coder, and GPT-OSS
• Real-time SSE Streaming - Full streaming support
• Tool Calling - Native function calling support
• Vision Support - Image analysis capabilities

Puter.com uses a "User-Pays" model:

1. No API keys - Just sign in with your Puter account
2. Users pay their own usage - Each Puter account has its own credit allocation
3. Free tier available - New accounts get free credits to start
4. Credits run out - When exhausted, you pay Puter directly or create a new account

Important Reality Check: Puter's marketing says "Free, Unlimited" but this is misleading. In practice:

• Free tier limits exist but are undocumented (GitHub Issue #1704)
• Users report limits trigger after "minimal usage" (GitHub Issue #1291)
• When limits hit, you'll see: "usage-limited-chat": Permission denied

Great fit! Your infrastructure cost is $0. Each of YOUR users authenticates with their OWN Puter account and pays for their own AI usage.

Caution: When YOU use this plugin during development, YOU are the user. YOUR Puter account's free tier gets consumed. Based on community reports, the free tier is limited and undocumented.

Estimated free tier: ~100 requests/day (unconfirmed, based on third-party reports)

Paste this into any LLM agent (Claude Code, OpenCode, Cursor, etc.):

Install the opencode-puter-auth plugin and configure Puter.com models
in ~/.config/opencode/opencode.json by following:
https://raw.githubusercontent.com/Mihai-Codes/opencode-puter-auth/main/README.md

1. Add the complete configuration to your opencode.json (~/.config/opencode/opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-puter-auth"],
  "provider": {
    "puter": {
      "npm": "opencode-puter-auth",
      "name": "Puter.com (500+ AI Models)",
      "models": {
        "claude-opus-4-5": {
          "name": "Claude Opus 4.5 (via Puter)",
          "limit": { "context": 200000, "output": 64000 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        },
        "claude-sonnet-4-5": {
          "name": "Claude Sonnet 4.5 (via Puter)",
          "limit": { "context": 200000, "output": 64000 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        },
        "claude-sonnet-4": {
          "name": "Claude Sonnet 4 (via Puter)",
          "limit": { "context": 200000, "output": 64000 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        },
        "claude-haiku-4-5": {
          "name": "Claude Haiku 4.5 (via Puter - Fast)",
          "limit": { "context": 200000, "output": 64000 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        },
        "gpt-5.2": {
          "name": "GPT-5.2 (via Puter)",
          "limit": { "context": 128000, "output": 32768 },
          "modalities": { "input": ["text", "image"], "output": ["text"] }
        },
        "gpt-4.1-nano": {
          "name": "GPT-4.1 Nano (via Puter - Ultra Fast)",
          "limit": { "context": 128000, "output": 16384 },
          "modalities": { "input": ["text", "image"], "output": ["text"] }
        },
        "gpt-4o": {
          "name": "GPT-4o (via Puter)",
          "limit": { "context": 128000, "output": 16384 },
          "modalities": { "input": ["text", "image"], "output": ["text"] }
        },
        "o3-mini": {
          "name": "o3-mini (via Puter - Reasoning)",
          "limit": { "context": 128000, "output": 32768 },
          "modalities": { "input": ["text"], "output": ["text"] }
        },
        "o4-mini": {
          "name": "o4-mini (via Puter - Reasoning)",
          "limit": { "context": 128000, "output": 32768 },
          "modalities": { "input": ["text"], "output": ["text"] }
        },
        "deepseek-r1": {
          "name": "DeepSeek R1 (via Puter - Reasoning)",
          "limit": { "context": 128000, "output": 32768 },
          "modalities": { "input": ["text"], "output": ["text"] }
        },
        "google/gemini-2.5-pro": {
          "name": "Gemini 2.5 Pro (via Puter - 1M Context)",
          "limit": { "context": 1000000, "output": 65536 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        },
        "google/gemini-2.5-flash": {
          "name": "Gemini 2.5 Flash (via Puter)",
          "limit": { "context": 1000000, "output": 65536 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        }
      }
    }
  }
}

2. Authenticate with Puter:

# Using the included CLI
npx opencode-puter-auth login

# Or if you have the plugin installed globally
puter-auth login

This opens a browser window for Puter.com login. Enter your Puter username and password.

Note: Puter is a custom provider, so it won't appear in opencode auth login. Use the CLI above to authenticate.

3. Verify authentication:

puter-auth status
# Or: npx opencode-puter-auth status

4. Use it:

opencode --model=puter/claude-opus-4-5

Puter acts as a gateway to OpenRouter, giving you access to 400+ additional models. Many of these have FREE tiers (:free suffix) with more generous limits than premium models.

Use the openrouter: prefix to access any OpenRouter model through Puter:

# Format: puter/openrouter:provider/model-name
opencode --model=puter/openrouter:deepseek/deepseek-r1-0528:free

Add these to your opencode.json models section:

{
  "provider": {
    "puter": {
      "npm": "opencode-puter-auth",
      "name": "Puter.com (500+ AI Models)",
      "models": {
        "openrouter:xiaomi/mimo-v2-flash:free": {
          "name": "MiMo-V2-Flash (Free - Best Open Source)",
          "limit": { "context": 262000, "output": 32768 },
          "modalities": { "input": ["text"], "output": ["text"] }
        },
        "openrouter:mistralai/devstral-2512:free": {
          "name": "Devstral 2 (Free - Agentic Coding)",
          "limit": { "context": 262000, "output": 32768 },
          "modalities": { "input": ["text"], "output": ["text"] }
        },
        "openrouter:deepseek/deepseek-r1-0528:free": {
          "name": "DeepSeek R1 0528 (Free - o1-level Reasoning)",
          "limit": { "context": 164000, "output": 32768 },
          "modalities": { "input": ["text"], "output": ["text"] }
        },
        "openrouter:qwen/qwen3-coder:free": {
          "name": "Qwen3 Coder 480B (Free - Massive Coder)",
          "limit": { "context": 262000, "output": 32768 },
          "modalities": { "input": ["text"], "output": ["text"] }
        },
        "openrouter:meta-llama/llama-3.3-70b-instruct:free": {
          "name": "Llama 3.3 70B (Free - Multilingual)",
          "limit": { "context": 131000, "output": 32768 },
          "modalities": { "input": ["text"], "output": ["text"] }
        },
        "openrouter:google/gemma-3-27b-it:free": {
          "name": "Gemma 3 27B (Free - Multimodal)",
          "limit": { "context": 131000, "output": 32768 },
          "modalities": { "input": ["text", "image"], "output": ["text"] }
        },
        "openrouter:openai/gpt-oss-120b:free": {
          "name": "GPT-OSS 120B (Free - OpenAI Open Weights)",
          "limit": { "context": 131000, "output": 32768 },
          "modalities": { "input": ["text"], "output": ["text"] }
        },
        "openrouter:google/gemini-2.0-flash-exp:free": {
          "name": "Gemini 2.0 Flash Exp (Free - 1M Context)",
          "limit": { "context": 1050000, "output": 65536 },
          "modalities": { "input": ["text", "image"], "output": ["text"] }
        }
      }
    }
  }
}

These models are completely FREE via Puter's OpenRouter gateway:

1. More Generous Free Limits - The :free models often have better rate limits than premium Puter models
2. Open Source - Many are fully open-source with transparent weights
3. Specialized - Models optimized for specific tasks (coding, reasoning, etc.)
4. Fallback Options - When premium models are rate-limited, fall back to free alternatives

You can use ANY model from OpenRouter's catalog by adding it to your config:

"openrouter:anthropic/claude-opus-4.5": {
  "name": "Claude Opus 4.5 (via OpenRouter)",
  "limit": { "context": 200000, "output": 64000 },
  "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
}

Note: Non-free models will consume your Puter credits based on OpenRouter pricing.

This plugin includes a built-in MCP (Model Context Protocol) server, allowing you to use Puter AI models in any MCP-compatible application like Zed IDE, Claude Desktop, Continue, and more.

1. Authenticate with Puter first:

npx opencode-puter-auth login

2. Add to your MCP client configuration:

For Zed IDE (~/.config/zed/settings.json):

{
  "context_servers": {
    "puter": {
      "command": {
        "path": "npx",
        "args": ["opencode-puter-auth", "serve", "--mcp"]
      }
    }
  }
}

For Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "puter": {
      "command": "npx",
      "args": ["opencode-puter-auth", "serve", "--mcp"]
    }
  }
}

For other MCP clients, use the command:

npx opencode-puter-auth serve --mcp

Or if installed globally:

puter-mcp

After setup, you'll have access to these tools:

Once configured, you can use the tools in Zed's Agent Panel:

Use puter-chat to ask Claude Opus 4.5 to explain this code

Use puter-models to list all available Anthropic models

Use puter-account to check my remaining credits

• 500+ AI Models - Access Claude Opus 4.5, GPT-5.2, Gemini 2.5 Pro, DeepSeek R1, and more
• No API Keys - Just sign in with your Puter account
• Free Tier - Try before you buy with Puter's free credits
• 400+ FREE OpenRouter Models - Use :free models with no cost
• Works Everywhere - Any MCP-compatible client (Zed, Claude Desktop, Continue, etc.)

You can also use the Puter AI SDK provider directly in your own applications:

import { createPuter } from 'opencode-puter-auth';

// Create a Puter provider instance
const puter = createPuter({
  authToken: 'your-puter-auth-token',
});

// Use with AI SDK
const model = puter('claude-opus-4-5');

// Or use specific methods
const chatModel = puter.chat('claude-sonnet-4-5');
const languageModel = puter.languageModel('gpt-4o');

This implements the full AI SDK v3 specification with:

• Non-streaming and streaming generation
• Tool/function calling support
• Reasoning/thinking token support
• Proper finish reason mapping

Create ~/.config/opencode/puter.json for advanced settings:

{
  "quiet_mode": false,
  "debug": false,
  "api_timeout_ms": 120000,
  "auto_create_temp_user": true,
  "max_retries": 3,
  "cache_ttl_ms": 300000
}

When a model returns HTTP 429 (rate limited) or 403 (forbidden), the plugin automatically tries free OpenRouter models. This keeps your workflow running even when premium models are temporarily unavailable.

1. You request a model (e.g., claude-opus-4-5)
2. If that model returns a rate limit error, it goes into "cooldown"
3. The plugin automatically tries the next available free model
4. A warning is logged showing which fallback model was used
5. Your request completes without manual intervention

When rate limits are hit, these free models are tried in order (20 models across 5 tiers):

Note: OpenRouter free models have daily rate limits: 50 requests/day without credits, or 1000 requests/day with 10+ credits purchased on your OpenRouter account.

In ~/.config/opencode/puter.json:

{
  "fallback_enabled": true,
  "fallback_cooldown_ms": 60000,
  "fallback_models": [
    "openrouter:xiaomi/mimo-v2-flash:free",
    "openrouter:deepseek/deepseek-r1-0528:free",
    "openrouter:mistralai/devstral-2512:free"
  ]
}

To disable fallback globally:

{
  "fallback_enabled": false
}

To disable fallback for a specific request (programmatic usage):

import { createPuter } from 'opencode-puter-auth';

const puter = createPuter({ authToken: 'your-token' });
const model = puter('claude-opus-4-5', { disableFallback: true });

• Rate-limited models are put on cooldown for fallback_cooldown_ms (default: 1 minute)
• Models on cooldown are skipped in favor of available models
• Cooldown automatically expires, allowing the model to be retried
• If all models (including fallbacks) are exhausted, the original error is thrown

For even more resilience, you can configure multiple Puter accounts. When one account hits rate limits, the plugin automatically rotates to the next available account.

1. Add multiple Puter accounts using puter-auth login
2. When the active account hits a rate limit, it goes into "cooldown"
3. The plugin automatically switches to the next available account
4. Your request continues without interruption
5. Cooldown accounts become available again after the cooldown period

# Add your first account
puter-auth login

# Add additional accounts (opens browser for each)
puter-auth login

# View all accounts
puter-auth status

The plugin supports two rotation strategies:

In ~/.config/opencode/puter.json:

{
  "account_rotation_enabled": true,
  "account_rotation_strategy": "round-robin",
  "account_rotation_cooldown_ms": 300000
}

Account cooldowns use exponential backoff:

• First rate limit: 1x cooldown (5 minutes)
• Second consecutive: 2x cooldown (10 minutes)
• Third consecutive: 3x cooldown (15 minutes)
• Fourth+ consecutive: 4x cooldown (20 minutes max)

This prevents hammering accounts that are consistently being rate-limited.

The plugin supports both model fallback and account rotation, and they work together:

When a request fails:

1. First, model fallback tries different models on the current account
2. If all models fail, account rotation switches to a different account
3. Model fallback then runs again on the new account

import { 
  AccountRotationManager, 
  getGlobalAccountRotationManager,
  AllAccountsOnCooldownError 
} from 'opencode-puter-auth';

// Get the global rotation manager
const rotation = getGlobalAccountRotationManager(authManager, {
  cooldownMs: 300000,
  strategy: 'least-recently-used',
});

// Check current status
const summary = rotation.getSummary();
console.log(`${summary.availableAccounts}/${summary.totalAccounts} accounts available`);

// Handle rate limit errors
try {
  await makeRequest();
} catch (error) {
  const result = await rotation.handleRateLimitError(error);
  if (result) {
    console.log(`Rotated to account: ${result.account.username}`);
    await makeRequest(); // Retry with new account
  } else {
    throw new AllAccountsOnCooldownError(rotation.getAccountStatuses());
  }
}

When debug: true is set, the plugin outputs detailed logs with timestamps:

[puter-auth] 15:30:45 Request: POST /drivers/call method=complete model=claude-opus-4-5 stream=true messages=3
[puter-auth] 15:30:45 Stream connected duration=234ms
[puter-auth] 15:30:47 Response: 200 Stream complete (2.1s)

If a request fails and retries:

[puter-auth] 15:30:45 Request: POST /drivers/call method=complete model=claude-opus-4-5
[puter-auth] 15:30:45 Retry 1/3: Rate limited (429), waiting 1000ms
[puter-auth] 15:30:46 Retry 2/3: Rate limited (429), waiting 2000ms
[puter-auth] 15:30:48 Response: 200 OK (3.2s)

Auth state changes:

[puter-auth] 15:30:45 Auth: Account added - username
[puter-auth] 15:30:45 Auth: Switched account - other_user

Fallback behavior:

[puter-auth] 15:30:45 Request: claude-opus-4-5
[puter-auth] 15:30:45 Rate limited (429), adding to cooldown
[puter-auth] 15:30:45 Fallback: trying openrouter:xiaomi/mimo-v2-flash:free
[puter-auth] 15:30:47 Response: 200 OK (used fallback model)

The plugin adds these tools to OpenCode:

• puter-models - List all available Puter models
• puter-account - Show current account info

Bottom line:

• Use Puter for building apps where your users authenticate with their own accounts
• Use Antigravity for your own development (more predictable ~300K tokens/day)
• Use Puter if you specifically need GPT-5 or DeepSeek (not available elsewhere free)

If you were using the old configuration format that piggybacked on Google (google/puter-* models), you need to update to the new standalone provider format.

{
  "plugin": ["opencode-puter-auth"],
  "provider": {
    "google": {
      "models": {
        "puter-claude-opus-4-5": { ... }
      }
    }
  }
}

{
  "plugin": ["opencode-puter-auth"],
  "provider": {
    "puter": {
      "npm": "opencode-puter-auth",
      "name": "Puter.com (500+ AI Models)",
      "models": {
        "claude-opus-4-5": { ... }
      }
    }
  }
}

1. Clear the plugin cache:

   rm -rf ~/.cache/opencode/node_modules/opencode-puter-auth
   rm -rf ~/.config/opencode/node_modules/opencode-puter-auth

2. Update your opencode.json:

   • Change provider.google.models.puter-* to provider.puter.models.*
   • Add "npm": "opencode-puter-auth" to the puter provider section
   • Remove the puter- prefix from model names

3. Update your model references:

   • Old: google/puter-claude-opus-4-5
   • New: puter/claude-opus-4-5

4. Re-authenticate:

   npx opencode-puter-auth login
   # Or: puter-auth login

The new standalone provider offers:

• Direct API access - No routing through Google/Antigravity infrastructure
• Dedicated CLI - Use puter-auth login for authentication
• Better reliability - Direct connection to Puter's API
• Cleaner model names - puter/claude-opus-4-5 instead of google/puter-claude-opus-4-5

This is a known issue affecting all users. See Current Status at the top of this README.

Technical details:

• Authentication works (/whoami returns your user)
• AI calls fail (/drivers/call returns 403)
• This is NOT geographic - tested from US and EU with same result
• This is NOT account-specific - affects all accounts

I'm working with the Puter team to resolve this. In the meantime, consider using Antigravity or direct API keys for AI access.

This means your Puter account has exhausted its free tier credits. Despite Puter's "Free Unlimited" marketing, limits do exist.

Solutions:

1. Switch to FREE OpenRouter models - Use puter/openrouter:xiaomi/mimo-v2-flash:free or other :free models (see OpenRouter section above)
2. Wait - Limits may reset (timing undocumented)
3. Add credits on Puter.com (paid)
4. New account - Create a new Puter account (new accounts get free credits)
5. Switch providers - Use Antigravity, OpenRouter free tier, or other free providers
6. Use lighter models - Haiku/Flash models may consume fewer credits than Opus

# macOS/Linux
rm -rf ~/.cache/opencode/node_modules/opencode-puter-auth
rm -rf ~/.config/opencode/node_modules/opencode-puter-auth

# Windows (PowerShell)
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\opencode\node_modules\opencode-puter-auth" -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force "$env:APPDATA\opencode\node_modules\opencode-puter-auth" -ErrorAction SilentlyContinue

# Restart opencode
opencode

# Manually visit:
http://localhost:19847

npx opencode-puter-auth login
# Or: puter-auth login

Note: Puter is a custom provider and won't appear in opencode auth login. You must use the plugin's CLI.

Increase timeout in puter.json:

{
  "api_timeout_ms": 300000
}

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Before your first PR can be merged, you'll need to sign our simple Contributor License Agreement (CLA) - just reply to the bot's comment.

	Mihai Chindris Creator & Lead Maintainer

Thanks to these wonderful people:

EldoDebug 🤔

icytz 🤔

If this plugin helps you, consider supporting its development:

• Puter.com - The amazing "Internet Computer" platform with 500+ AI models
• OpenCode - The best AI coding agent
• OpenRouter - Unified API for 400+ AI models with generous free tiers
• opencode-antigravity-auth - Inspiration for plugin architecture
• opencode-openai-codex-auth - Inspiration for installer and configuration patterns

MIT - See LICENSE

Made with love by @chindris-mihai-alexandru