Agent

An agent is a directory in a git repo with an oc-agent.yaml file. The platform reads this file to know which runtime to use, then provisions a sandboxed VM with the full directory as the agent's workspace. That's the core idea — a git-backed directory becomes a running agent with minimal config.

my-agent/
├── oc-agent.yaml       # required: defines the agent
├── AGENT.md            # optional: instructions for the runtime
├── scripts/            # optional: tooling the agent can use
└── data/               # optional: files the agent creates across sessions

The minimal oc-agent.yaml is one line:

runtime: claude-code

Git as source of truth

Git is the source of truth for two things: how the agent is provisioned (the oc-agent.yaml config) and what the agent has access to (the workspace files). This gives you:

• Reproducibility. Every session starts from a specific git ref (branch, tag, or commit SHA). You always know exactly what the agent looked like when a session ran.
• History. Config changes, new scripts, new files — git tracks all of it.
• Portability. Clone it, fork it, share it. No platform lock-in.

When a session is provisioned, the platform clones the repository at the specified ref and sets the working directory to the agent's directory. The agent gets a full copy of the repo on disk.

After a session ends, workspace changes (new files, modified data, outputs) can be persisted back to git via ocr persist. This is how agents carry state across sessions — through files in git, not through hidden platform state.

What oc-agent.yaml does and doesn't cover

oc-agent.yaml is purely structural. It declares which runtime to use and optional metadata (name, description, model). It does not define behavior.

This separation is intentional. The runtimes already have their own conventions for instructions (CLAUDE.md for Claude Code, AGENTS.md for Codex) and tool configuration. OpenCompany doesn't reinvent any of that — it just tells the platform which runtime to launch and gets out of the way.

Multiple agents in one repo

Any directory containing an oc-agent.yaml is a valid agent. A single repo can hold multiple agents:

my-company-agents/
├── agents/
│   ├── pr-reviewer/
│   │   ├── oc-agent.yaml
│   │   └── AGENT.md
│   └── deploy-bot/
│       ├── oc-agent.yaml
│       └── scripts/
└── shared/
    └── utils.sh

Each agent's identity is <repo>:<relative-path>, not just the name field. Two agents named bot in different directories are distinct agents.

Rules:

• An agent can read the entire repo during a session. Shared resources (libraries, data, configs) in common directories are accessible.
• An agent can only persist changes to its own directory. Changes outside the agent's workspace are discarded at persist time.
• Security boundary is the repo boundary. If agents need isolation from each other's files, put them in separate repos.

For most cases, one agent per repo is the simplest setup. Multi-agent repos are useful when agents share code or data and belong to the same team.