Mastering OpenCode agent configuration

devsecops July 15, 2026 · 10 min · #opencode #agents #llm #security

OpenCode is an open-source, multi-model coding agent (Claude, OpenAI, Ollama, Gemini…), designed as an open alternative to Claude Code or Cursor. One of its strengths: agents are configured in Markdown + YAML front-matter, with a fine-grained permission system. Here’s what you need to know.

1. Difference between agent (primary) and subagent

  • mode: agent (primary) — the entry agent, launched directly from the terminal (opencode --agent my-agent). It has the global view of the problem.
  • mode: subagent — a discreet “specialist”. It cannot be launched by the user directly; it waits to be called by a primary agent for a highly targeted task.

2. Is this format limited to OpenCode?

The specific syntax (YAML front-matter combined with Markdown for instructions) and the permission system (allow, ask, deny) are specific to OpenCode and its security architecture. But the concept of configuring agents via a Markdown or JSON file is a de-facto standard found in other agent frameworks (Aider, Cursor Rules, AutoGPT), with different keywords.

3. Available permissions

All permissions are declared in the permission: block of the front-matter:

  • read — reading files
  • edit — writing and modifying files (write, patch)
  • bash — running commands in the terminal
  • webfetch — internet access (HTTP requests, downloading pages)
  • task — delegating to a subagent
  • glob — searching files/folders
  • grep — searching text inside files
  • environment — reading system environment variables

4. Handling deny blocks

An agent cannot bypass a deny: OpenCode blocks the action at the system level and returns a strict error. To have a blocked action documented automatically, allow a precise command and add a rule in the instructions:

permission:
  bash:
    "gh issue create *": allow # Allows creating a GitHub issue

Then, in the Markdown body: “If you get blocked by missing permissions or a technical restriction, use gh issue create to document the problem and list the files you couldn’t modify.”

5. Should you ask an AI to write the instructions?

Yes — with one condition: give it the exact technical context. Example prompt:

“Act as a prompt engineer. Write an OpenCode agent file in Markdown format. Use a direct tone, imperative rules as bullet lists, and define the strictly necessary YAML permissions for the role of [your role].”

6. Concrete example: monitoring agent

A subagent that scans the code, detects key metrics and generates Prometheus/Grafana configurations:

---
name: monitoring-exporter
description: "Agent detecting critical points and generating Prometheus/Grafana configs."
mode: subagent
temperature: 0.1
permission:
  read: allow
glob: allow
grep: allow
edit: ask
bash:
  "promtool check rules *": allow
  "*": deny
---
You are a virtual SRE engineer expert in OpenTelemetry, Prometheus and Grafana.

## Mission
1. Analyze the codebase to identify APIs, heavy DB queries and critical functions.
2. Generate or update Prometheus config files (`alerting.rules.yml`).
3. Create importable Grafana dashboards in `./monitoring/dashboards/`.

## Strict rules
- Before validating an alert rules file, run `promtool check rules <file>`.
- Naming standard: `app_[module]_[action]_total`.
- Never modify application code (`src/`); list needs in `MONITORING_TODO.md`.

7. Architecture of an AI-Factory

To orchestrate a software factory, structure it as a hub-and-spoke: a primary agent (product owner / architect) distributes work to specialized subagents (front, back, ops). The primary agent breaks the project into tasks and only calls subagents via task: allow. A PO never codes directly.

8. Tool use: what exactly is it?

Tool use is an intrinsic capability of the model: OpenCode gives the model a list of available functions (read a file, run a command…), and the model decides to call one. A subagent, on the other hand, is a full entity with its own LLM, instructions and permissions — a “specialized colleague”, not just a tool.

9. Security: don’t trust the YAML alone

Agent permissions are only a visual aid; OpenCode provides no built-in sandbox. For an autonomous AI-Factory, Docker isolation is mandatory: hardened image, non-root user, internal network for agents, and a single gateway allowed to talk to GitLab. Also note that free OpenRouter models disable tool use — prefer paid or local models.

10. The multi-server pitfall

A known bug involving multiple OpenCode servers in parallel: sessions created via the TUI tend to ignore the local opencode.json and pick the last used model from the shared database (~/.local/share/opencode/opencode.db). The fix: interact exclusively through the HTTP API (POST /session), which strictly respects the target server’s config file — or physically separate instances on distinct machines/containers.

Written by Rulx Philomé Alexis · ← All notes