Contents

Guides

Set Up OpenCode (Bring Your Own Key)

•6 min read
Set Up OpenCode (Bring Your Own Key)

Set Up OpenCode (Bring Your Own Key)

OpenCode is Ritemark's third AI runtime, sitting alongside Claude Code and Codex. The difference is the billing model. Claude Code and Codex sign in with their own accounts. OpenCode is bring-your-own-key — point it at any provider you already have an API key for and pick from that provider's models.

If you already pay OpenAI directly for API usage, or you have a Google AI key for Gemini, or you run an OpenRouter account, OpenCode lets you reuse those keys inside Ritemark.

Settings → OpenCode showing API key fields and the Auto-approve toggle

What You Need

You need at least one API key from one of these providers:

You can configure as many as you like. Only providers with a saved key appear in the model picker.

Step 1: Open Settings → OpenCode

Open Ritemark Settings (Cmd+, on macOS, or the gear icon in the activity bar). Find the OpenCode section. You will see four API-key fields, one per provider, and a single Auto-approve edits & tool calls toggle.

The OpenCode binary itself is already bundled with Ritemark — there is no separate install. It runs as a child process driven over the Agent Client Protocol (ACP), the same protocol Codex uses. On macOS, the bundled binary is re-signed under Ritemark's own Developer ID with hardened runtime, so it launches cleanly without Gatekeeper warnings.

Step 2: Paste Your API Keys

Paste each key into its provider field and press Enter or click outside the field to save. Keys are stored in your operating system's secure credential store — Keychain on macOS, Credential Manager on Windows.

The moment you save a key, the OpenCode group in the AI sidebar's model picker refreshes. You do not need to reload Ritemark.

OpenCode group in the model picker showing Gemini models after a Google AI key is saved

If no keys are configured, the OpenCode section in the model picker prompts you to open Settings instead of showing an empty list.

Step 3: Pick an OpenCode Model

Open the AI sidebar and click the model dropdown at the top. You should see three groups:

  1. Claude Code — your existing Claude account models.
  2. Codex — your existing ChatGPT account models.
  3. OpenCode — every model from every provider you have configured.

Select any OpenCode model and start chatting. Responses stream in as you would expect. Reasoning is summarized as a small number of "Thinking" entries instead of hundreds of one-word activity lines, so the activity log stays readable. Tool calls appear as activities.

File Change Approval

When OpenCode wants to edit an open file, you get a single File Change Approval card with the target path. The file on disk stays untouched until you click Approve.

This works the same way for every OpenCode-driven edit, regardless of which model produced it. Approval is per file change, not per session.

Two important guard rails:

  • Out-of-workspace writes are auto-rejected. OpenCode cannot write to a file outside your current Ritemark workspace. No prompt, no toggle — the write is blocked at the bridge layer.
  • Approval is required even on small edits. A single-character change still produces an approval card.

Auto-approve Edits and Tool Calls

When you want OpenCode to run hands-free — for example during a long refactor or a multi-file translation — flip the Auto-approve edits & tool calls toggle in Settings → OpenCode.

With auto-approve on:

  • Edits inside the workspace proceed without an approval card.
  • Tool calls proceed without an approval card.

With auto-approve on, this still holds:

  • Writes outside the workspace remain blocked. Auto-approve does not unlock that path. If you need OpenCode to touch files outside your project, you have to move them inside the workspace first.

Turn auto-approve off again when you want approval cards back. The toggle is global across OpenCode sessions, not per conversation.

What Each Provider Is Good For

A rough guide. Pick what matches your workflow.

Provider Strong for Notes
OpenAI General writing, code reasoning, fast turn-around GPT-4o family is widely supported
Google AI Long-context tasks, multilingual content Gemini's context window is generous
Anthropic Same Claude models as Claude Code, but paid through your API key Useful if you want Claude without the Claude.ai subscription path
OpenRouter Trying many models from one key Aggregates dozens of providers behind a single bill

You can switch models mid-conversation. The conversation history follows the thread, not the model.

Privacy

Your API keys live in your OS credential store. Ritemark does not transmit them anywhere except to the provider you configured them for.

Each turn you send through OpenCode goes to the provider that owns the selected model. There is no Ritemark proxy, no Ritemark account, and no Ritemark cloud — the traffic goes directly from your machine to the provider you chose.

Troubleshooting

The OpenCode group shows "Add API keys to use OpenCode"

You have not saved any provider keys yet. Open Settings → OpenCode and paste at least one key.

A new key does not appear in the model picker

The picker should refresh instantly when a key is saved. If it does not, switch sidebars (Explorer to AI and back) to force a re-read. As of v1.7.3 the picker also re-reads on focus.

A model is rejected with "out-of-workspace write blocked"

OpenCode tried to write a file outside your current Ritemark workspace. Move the target file inside the workspace and retry, or rephrase the request so the agent works only inside your project tree.

"Plan Approval" card looks blocked

The plan-approval card now reliably renders the full plan and stays on screen only while the agent is genuinely waiting on you. If you see Approve/Reject buttons with no plan content, that is the old behaviour — make sure you are running v1.7.3 or later.

macOS Gatekeeper warning when launching OpenCode

The OpenCode binary shipped with v1.7.3 and later is re-signed under Ritemark's Developer ID with hardened runtime. If you see a Gatekeeper warning, you are running an older version — update Ritemark and the warning goes away.

Quick Reference

Action How
Open OpenCode settings Settings → OpenCode
Add a provider key Paste into the provider field, press Enter
Switch to an OpenCode model Model picker → OpenCode group → pick a model
Approve an edit Click Approve on the File Change Approval card
Run hands-free Toggle Auto-approve edits & tool calls
Block a write outside the workspace Automatic — always on, even with auto-approve
Back to support