concept

Understand the opencompany platform.

OpenCompany is an open platform for running AI agents across your company. Push any folder with a valid config. The platform handles the VM, the permissions, the secrets, and the audit trail.

# Building your agent

An agent is a folder.

Any folder. The only requirement is a valid oc-agent.yaml at the root. The YAML declares the agent's name, runtime, model, which files to sync back, and which markdown files compose the system prompt.

Everything else in the folder is up to you. Scripts, CSVs, markdown prompts, JSON data — the structure is arbitrary. All of it becomes the agent's seed: the starting state that gets snapshotted into every session.

Run oc push and you're deploying. We handle VM provisioning, permissions, integration wiring, and the full audit trail.

seed folder

pr-reviewer/
├── oc-agent.yaml
├── AGENT.md
├── CONTEXT.md
├── RULES.md
├── data/
│   └── past-reviews.json
└── reports/
    └── .gitkeep

oc-agent.yaml

name: pr-reviewer
description: Reviews PRs
runtime: oc-native
model: opus

sync:
  - data/
  - reports/*.md

system_prompt:
  - AGENT.md
  - CONTEXT.md
  - RULES.md

$ oc push ./pr-reviewer
  validating oc-agent.yaml .... ok
  uploading seed folder ....... ok
  provisioning agent .......... ok
  agent live: pr-reviewer

# Using your agent

Launch a session. The platform does the rest.

Launch from the web app with one click — or from the CLI with oc run. The platform snapshots the seed folder into a fresh, isolated VM.

The harness boots inside the VM, composes the system prompt, connects the model, provisions integrations, and starts the agent loop. The agent runs with its own sandbox, its own filesystem, and its own capabilities — all gated through the action gateway.

When the session ends, files matching the sync pattern are written back to the seed folder and committed to git. Everything else is discarded with the VM.

The seed grows only with what you declare. That's the loop.

session lifecycle

vm provisioned

seed folder snapshotted

system_prompt composed

integrations provisioned

agent loop running

session ends

sync data/*, reports/*.md → seed folder

vm discarded

# Refining your agent

Three levers to customize everything.

The system prompt shapes how the agent thinks. Capabilities give it real power. Sync patterns control what persists.

System prompt

AGENT.md    → identity
CONTEXT.md → knowledge
RULES.md   → constraints

Markdown files, composed
top to bottom. Define who
the agent is, what it
knows, what it can't do.

Capabilities

skills        → prompt routines
integrations  → slack, github..
tools         → search, scrape
sub-agents    → spawn others

Each permission-gated.
Each in its own sandbox.

Sync pattern

sync:
  - data/
  - reports/*.md

What goes back to seed.
Everything else discarded.
This is how agents learn
across runs.

# Permission model

Every action is gated.

Set permissions per-action in the agent config. Three levels: allow, block, or pause for human approval.

onAllow

Executes immediately. No human in the loop. Use for read-only or low-risk actions.

github.list_prs: on

askPause

Session pauses for human approval. Use for anything destructive, expensive, or externally visible.

github.merge_pr: ask

offBlock

Blocked entirely. The agent is told it cannot do this. Use for actions it should never take.

github.delete_repo: off

# Sync patterns

What survives a session.

Sync declares what gets written back to the seed folder and committed to git. Everything else is discarded with the VM. Be deliberate — the sync field is the only way data escapes the sandbox.

data/

Persistent knowledge the agent accumulates across sessions. Metrics, preferences, indexed content.

reports/*.md

Session output. Summaries, reviews, analysis. Glob patterns capture a category without listing individual files.

logs/session-*.json

Structured session logs for debugging or auditing agent behavior over time.

# Deploy and iterate

Push. Run. Read. Adjust. Repeat.

$ oc push ./pr-reviewer
  validating oc-agent.yaml ... ok
  uploading seed folder ...... ok
  agent registered: pr-reviewer

$ oc run pr-reviewer
  session: ses_8f3k2x
  sandbox ready
  agent loop running

$ oc logs pr-reviewer --session latest
  [09:41:02] reviewing PR #42
  [09:41:14] ocr github.create_review → 201
  [09:41:15] ocr slack.send → 200
  [09:41:16] session complete
  synced: reports/pr-42-review.md

$ oc diff pr-reviewer
  seed folder changes after session:
  + reports/pr-42-review.md