Profiles Overview

​

Overview

​

When to Use Profiles

• When you work across multiple repositories and want consistent configuration.
• When you contribute to open source projects and need zero-footprint configuration.
• When you need to control what OpenCode sees in untrusted repositories.
• When you maintain separate configurations for work, personal, and client projects.

​

Core Concepts

​

Global vs Local Mode

​

What Is Inside a Profile

• ocx.jsonc — OCX settings (registries, exclude/include patterns, custom binary)
• opencode.jsonc — OpenCode configuration
• AGENTS.md — Instructions for AI agents

​

How It Works

1. Profile Resolution: OCX resolves the active profile using a priority chain (local config → CLI flag → env var → default profile → none).
2. Instruction Discovery: OCX discovers instruction files walking up from the project directory to the git root.
3. Pattern Filtering: Exclude/include patterns from the active profile filter which project instruction files OpenCode receives.
4. Launch: OpenCode starts with the profile configuration and filtered instructions.

​

Profile Selection Priority

1. profile field in .opencode/ocx.jsonc (project-specific profile)
2. --profile <name> / -p <name> flag (explicit override)
3. OCX_PROFILE environment variable
4. default profile (if it exists)
5. No profile (base configurations only)

​

Directory Structure

​

Global Profiles

~/.config/opencode/
├── ocx.jsonc                 # Global base config
└── profiles/
    ├── default/
    │   ├── ocx.jsonc         # Profile OCX settings
    │   ├── opencode.jsonc    # Profile OpenCode config
    │   └── AGENTS.md         # Profile instructions
    └── work/
        ├── ocx.jsonc
        ├── opencode.jsonc
        └── AGENTS.md

​

Local Project Config

.opencode/                    # Local config
├── ocx.jsonc                 # Local OCX config
└── opencode.jsonc            # Local OpenCode config

​

Related Concepts

• Profile Configuration — Detailed configuration reference for exclude/include patterns and instruction discovery.
• Profile Security — Lock down recipes for untrusted repositories.
• CLI: Profile Commands — Full command reference for profile management.

​

See Also

• Quick Start — Set up your first profile.
• Enterprise Overview — Registry locking and integrity verification for teams.