oc-agent.yaml

The oc-agent.yaml file defines an agent. Place it in any directory within a git repository to make that directory an agent.

Minimal example

runtime: claude-code

Full example

runtime: claude-code
name: pr-reviewer                                              # optional
description: Reviews pull requests for code quality and security issues  # optional
model: opus                                                    # optional

Fields

`runtime`

Required. The agent runtime to use.

Value	Runtime
`claude-code`	Claude Code by Anthropic
`codex`	Codex CLI by OpenAI

The platform starts this runtime when launching a session.

`name`

Optional. A human-readable display name for the agent.

Default: the directory name containing oc-agent.yaml
Used in: dashboards, logs, CLI output
Not an identifier. Agent identity is <repo>:<relative-path>, not this field.

name: pr-reviewer

`description`

Optional. A short description of what the agent does.

Used in: dashboards, agent listings, search
Keep it to one sentence.

description: Reviews pull requests for code quality and security issues

`model`

Optional. The AI model the runtime should use.

Default: the runtime's default model
Values: passed through to the runtime as-is

Claude Code models:

Value	Model
`opus`	Latest Claude Opus (currently Opus 4.6)
`sonnet`	Latest Claude Sonnet (currently Sonnet 4.6)
`haiku`	Latest Claude Haiku
`claude-opus-4-6`	Pinned to specific version
`claude-sonnet-4-6`	Pinned to specific version

Codex models:

Value	Model
`o4-mini`	Default Codex model
`o3`	OpenAI o3
`gpt-4.1`	GPT-4.1

Use aliases (opus, sonnet) to stay on the latest version. Use full model names (claude-opus-4-6) to pin a specific version.

model: opus

File structure

The oc-agent.yaml file lives at the root of the agent's directory. Everything in that directory is the agent's workspace.

my-agent/
├── oc-agent.yaml       # agent config (this file)
├── AGENT.md            # instructions for the runtime (optional)
├── scripts/            # tooling (optional)
└── data/               # files created across sessions (optional)

Instructions and prompts belong in runtime-specific files (CLAUDE.md for Claude Code, AGENTS.md for Codex), not in oc-agent.yaml. See Agent for the full model.

Planned fields

Future versions of the spec will add:

skills — capabilities added to the agent
integrations — connections to external services with per-agent permissions
secrets — encrypted values injected at runtime
automations — triggers that spawn sessions (cron, webhook, events)
config — runtime-specific options (max turns, allowed tools)

These fields are not yet part of the spec. V1 covers identity and runtime only.

oc-agent.yaml

On this page