opencode-puter-setup

Auto-configure Puter as an OpenCode provider, giving you access to Claude Sonnet 4.6 for free — with optional prompt caching.

What This Does

• Adds two Puter provider entries to your OpenCode config
• Stores your Puter auth token in the OpenCode auth file
• Zero external dependencies beyond Node.js 18+

| Provider entry | Model | Endpoint | Prompt caching | |---|---|---|---| | puter-openai | Claude Sonnet 4.6 (Puter) | OpenAI-compatible | No | | puter-anthropic | Claude Sonnet 4.6 — Cached (Puter) | Anthropic-wire | Message-level only |

Caching limitation: Puter's Anthropic endpoint normalises system prompts to plain strings, which strips cache_control. Caching works on user/assistant message content, but not on system prompts.

Installation

# No install required
npx opencode-puter-setup

# Or install globally
npm install -g opencode-puter-setup
opencode-puter-setup

Quick Start

1. Get your token at https://puter.com → Settings → API Tokens
2. Run the setup and paste it in when prompted
3. Restart OpenCode, run /models, and select either Puter model

What Gets Written

~/.config/opencode/opencode.json (or local .opencode/config.json):

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "puter-openai": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Puter",
      "options": {
        "baseURL": "https://api.puter.com/puterai/openai/v1/"
      },
      "models": {
        "anthropic/claude-sonnet-4-6": {
          "name": "Claude Sonnet 4.6 (Puter)"
        }
      }
    },
    "puter-anthropic": {
      "npm": "@ai-sdk/anthropic",
      "name": "Puter (Cached)",
      "options": {
        "baseURL": "https://api.puter.com/puterai/anthropic/v1/",
        "apiKey": "puter"
      },
      "models": {
        "anthropic/claude-sonnet-4-6": {
          "name": "Claude Sonnet 4.6 — Cached (Puter)"
        }
      }
    }
  }
}

~/.local/share/opencode/auth.json — token stored with 0600 permissions.

Billing

Puter uses a user-pays model. Your free tier covers typical usage. No charges to you as the developer.

Troubleshooting

Model not showing in /models — restart OpenCode after setup.

401 errors — your token may have expired. Re-run the setup with a fresh token.

Caching not reducing costs — system prompt caching is not supported through Puter. Use message-level cache_control on large repeated user/assistant content instead.

License

MIT