> ## Documentation Index
> Fetch the complete documentation index at: https://ocx.kdco.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Profiles Overview

> Portable OpenCode configuration that works across repositories without modifying projects

## Overview

Profiles give you a global configuration system that lives outside your project directories. Instead of initializing `.opencode/` in every repository, you define your settings once and bring them anywhere.

## 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

| Aspect               | Local Mode                   | Profile Mode                          |
| -------------------- | ---------------------------- | ------------------------------------- |
| Config location      | `./.opencode/`               | `~/.config/opencode/profiles/<name>/` |
| Modifies repo        | Yes                          | No                                    |
| Per-project settings | Yes                          | Profile-isolated                      |
| Requires `ocx init`  | Yes                          | No (uses profile config)              |
| Visibility control   | No                           | Yes (exclude/include)                 |
| Registry scope       | Project-only                 | Profile-isolated                      |
| Best for             | Single project customization | Multi-project workflows               |

### What Is Inside a Profile

Each profile lives in `~/.config/opencode/profiles/<name>/` and contains:

* `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

Profiles are resolved in this order:

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

```text theme={null}
~/.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

```text theme={null}
.opencode/                    # Local config
├── ocx.jsonc                 # Local OCX config
└── opencode.jsonc            # Local OpenCode config
```

## Related Concepts

* [Profile Configuration](/docs/profiles/configuration) — Detailed configuration reference for exclude/include patterns and instruction discovery.
* [Profile Security](/docs/profiles/security) — Lock down recipes for untrusted repositories.
* [CLI: Profile Commands](/docs/cli/profile) — Full command reference for profile management.

## See Also

* [Quick Start](/docs/getting-started/quick-start) — Set up your first profile.
* [Enterprise Overview](/docs/enterprise/overview) — Registry locking and integrity verification for teams.