What Is opencode.json? Configuration and Security Manifest for the OpenAI Plugins Repository

The opencode.json file acts as a security and runtime manifest that configures how AI tools like opencode.ai interact with the OpenAI plugins repository, restricting operations to read-only access on cached snapshots while defining model preferences and provider routing.

The opencode.json file in the openai/plugins repository serves as the central configuration file for AI-assisted code analysis. Located at the repository root, this JSON manifest controls permissions, selects the large language models (LLMs) used for analysis, and specifies provider routing options for the opencode.ai platform.

Permission Rules and Access Control

The configuration implements a permission-based security model that explicitly restricts AI tool capabilities. According to the source code in opencode.json, permitted operations include read, grep, glob, list, and lsp, while potentially destructive actions such as write, edit, and bash are denied.

The file grants specific access only to /cache/repos/github.com/openai/plugins/main/**, ensuring the AI can interact exclusively with cached repository snapshots rather than live code. This path restriction prevents accidental modifications to the working repository during automated analysis tasks.

Model Selection and Fallback Strategy

The manifest specifies default LLM configurations using OpenRouter model identifiers. The primary model is set to openrouter/openai/gpt-oss-120b, with a fallback option of openrouter/qwen/qwen3-32b for scenarios requiring different computational characteristics or availability.

This dual-model approach ensures continuity of service while balancing performance requirements. The configuration allows the opencode.ai tooling to automatically switch to the Qwen model if the primary GPT-OSS model becomes unavailable or unsuitable for specific analysis tasks.

Provider Routing and HTTP Headers

opencode.json includes provider-specific options for API routing through OpenRouter. The configuration defines custom HTTP headers including OpenRouter-App-Title: Instagit and OpenRouter-App-URL: https://instagit.com for request identification.

The manifest establishes backend priority lists for model inference. The main model routes through Fireworks first, then falls back to Cerebras, while the fallback model prioritizes Sambanova followed by Groq. This tiered routing ensures optimal availability across different inference backends.

Security Architecture and Safety Guarantees

The configuration establishes a read-only security boundary that prevents unintended modifications to the codebase. By explicitly denying write operations and limiting file system access to cached repository copies, opencode.json ensures AI-assisted exploration for documentation generation, code navigation, and automated review cannot alter production files or execute arbitrary system commands.

This design allows safe integration of AI tooling into development workflows without risking repository integrity or exposing sensitive execution environments to automated agents.

Practical Implementation Examples

Developers can parse opencode.json to programmatically enforce these constraints. The following examples demonstrate permission validation and API request construction using the configuration values.

import json
import pathlib

# Load the configuration

config_path = pathlib.Path("opencode.json")
with config_path.open() as f:
    cfg = json.load(f)

# Example: check if a read operation is allowed for a given path

def can_read(path: str) -> bool:
    perms = cfg["permission"]["read"]
    # Direct match or wildcard

    return perms.get(path, perms.get("*", "deny")) == "allow"

print(can_read("/cache/repos/github.com/openai/plugins/main/README.md"))  # → True

print(can_read("some/other/file.py"))                                    # → False

# Bash example using the defined provider options

curl -H "OpenRouter-App-Title: Instagit" \
     -H "OpenRouter-App-URL: https://instagit.com" \
     https://api.openrouter.ai/v1/models/openai/gpt-oss-120b/completions \
     -d '{"prompt":"Explain opencode.json"}'

These implementations illustrate how client applications can consume the permission maps and provider settings defined in opencode.json to maintain consistent security boundaries across AI-assisted workflows.

Summary

• opencode.json serves as the central security manifest for AI tooling in the OpenAI plugins repository.
• The configuration restricts operations to read-only access on specific cached paths while blocking write and execution commands.
• It configures dual-model support with openrouter/openai/gpt-oss-120b as primary and openrouter/qwen/qwen3-32b as fallback.
• Provider routing options include custom OpenRouter headers and prioritized backend selections (Fireworks → Cerebras for primary, Sambanova → Groq for fallback).
• This architecture enables safe AI-assisted code analysis without risk of unintended repository modifications or security breaches.

Frequently Asked Questions

What operations are permitted according to opencode.json?

The configuration permits read-only operations including read, grep, glob, list, and lsp. It explicitly denies write, edit, bash, and most other operations that could modify the repository or execute system commands, ensuring AI tools maintain a safe, non-destructive interaction model.

Which LLM models are configured in the OpenAI plugins opencode.json?

The primary model is openrouter/openai/gpt-oss-120b, with openrouter/qwen/qwen3-32b serving as the fallback model. Both are accessed through the OpenRouter API infrastructure, with the configuration defining specific provider priorities for each model to ensure high availability.

Why does opencode.json restrict access to cached repository paths?

The configuration limits file system access to /cache/repos/github.com/openai/plugins/main/** to ensure AI tools interact only with static snapshots rather than live repository files. This safety mechanism prevents automated tools from accidentally modifying production code or accessing sensitive files outside the cached analysis context during documentation or review tasks.

How are API providers prioritized in the configuration?

The manifest defines provider chains where the main model routes through Fireworks first, then Cerebras if unavailable, while the fallback model uses Sambanova followed by Groq. This prioritization ensures optimal availability and performance across different model inference backends while maintaining consistent API headers for request tracking.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}