Profile format

A profile is a directory of text files. Editing the files IS building the agent — no SDK, no build step. This page is the reference for the fields you'll actually use: the directory layout, every everyday agent.json field with its default, and the companion files (SOUL.md, AGENTS.md, skills/, tools/, helpers/). A few UI/product-internal fields (productId, locked, and the panes layout block) are omitted here — they're set by the desktop app, not hand-edited.

profiles/my-agent/
├── agent.json          # Required — WHAT the agent can do (validated by ProfileSchema)
├── SOUL.md             # System prompt — WHO it is (identity, rules, persona)
├── AGENTS.md           # Memory — learned preferences, project context
├── skills/             # Skills — markdown how-tos it can invoke
│   └── summarize.md
├── tools/              # Custom tools — TypeScript/JavaScript files
│   └── my-tool.ts
└── helpers/            # Private subagents — nested profiles only this parent can spawn
    └── researcher/
        ├── agent.json
        └── SOUL.md

Only agent.json is required. Every field in it has a sensible default, so the minimum valid profile is:

{ "name": "my-agent" }

Everything below is optional and defaulted. The schema is validated by ProfileSchema in @ownware/cortex — an invalid config fails loudly at load with a clear message.

agent.json — identity

agent.json — model

agent.json — tools

Controls which tools exist. Filtering, connectors, and custom tools all live under tools.

"tools": {
  "preset": "full",
  "deny": ["shell_execute"],
  "allow": [],
  "custom": [{ "path": "tools/my-tool.ts" }],
  "mcp": {
    "github": { "transport": "stdio", "command": "npx",
                "args": ["-y", "@modelcontextprotocol/server-github"] }
  },
  "composio": { "toolkits": ["gmail", "slack"] }
}

Tool presets

coding includes shell_execute — it is not filesystem-only. If you want files without a shell, use readonly (reads only) or full with "deny": ["shell_execute"].

Connecting MCP, Composio, and custom tools is covered end-to-end in Tools & connectors.

policies — input guards

policies is a separate top-level array that governs which inputs a tool accepts once it exists (distinct from tools.deny, which governs whether it exists at all). Today the one guard kind is shell:

"policies": [
  {
    "kind": "shell",
    "tool": "shell_execute",
    "allowPrefixes": ["ls", "git status", "git diff"],
    "denyPatterns": ["^rm ", "^sudo "],
    "allowDangerous": false,
    "allowInjection": false
  }
]

The engine's shell-security floors (Level 1 irreversible, Level 4 exfiltration, Level 5 PII) are always enforced — a policy cannot opt out of them. See Security overview.

agent.json — system prompt

agent.json — memory

Persistent memory loaded into context across conversations.

"memory": { "enabled": true, "sources": ["AGENTS.md"], "autoLearn": true, "isolation": "shared" }

agent.json — skills, context, workspace

"skills":  { "dirs": ["skills/"], "external": [] },
"context": { "git": true, "cwd": true, "datetime": true, "project": true },
"workspace": { "mode": "cwd", "isolation": "shared", "dirs": [] }

skills — where the agent's skills come from. dirs are folders inside the profile (default ["skills/"]); external are additional skill sources.

context — granular system-prompt fragments, each individually toggleable:

workspace — mode (cwd | managed | temp), isolation (shared | per_profile | per_run), and extra dirs the agent may work in.

agent.json — security

Three layers: which security level applies, what permission mode does on sensitive actions, and zone classification. Full model in Security overview.

"security": {
  "level": "standard",
  "permissionMode": "ask",
  "sandbox": { "enabled": false, "provider": "local" },
  "zones": { "enabled": true, "combinationRules": "none" },
  "hitlTimeoutMs": 1800000
}

Security levels — level picks a preset posture that tunes the zone thresholds, audit/sanitize flags, and output caps (it feeds createZoneConfig(); it is not a literal per-action approval matrix). From loosest to tightest:

Regardless of level, decisions are allow or ask (Ownware never auto-writes a deny rule), and the shell floors (L1 destructive / L4 exfiltration / L5 PII) always apply — even at permissive. For the exact mechanics see the Security overview.

zones sub-fields: enabled (default true), maxAutoZone / maxAskZone (raise/lower the auto-allow and ask thresholds across the 7 zones safe→never; the 6 addressable ones run safe→machine, with never always blocked), overrides ([{ tool, zone, reason? }] to pin a tool to a zone), and combinationRules (none default, or default-set to enable the five cross-call exfiltration rules — appropriate for enterprise/legal/health profiles).

agent.json — execution, browser, compaction, checkpoint, hooks

"execution":  { "mode": "foreground", "timeout": "30m", "maxCostUsd": 5.0 },
"compaction": { "strategy": "summarize", "trigger": { "type": "fraction", "threshold": 0.8 } },
"checkpoint": { "store": "file" }

hooks

Attach behavior to the agent's lifecycle — audit, notify, archive, pause-for-approval, or run a script. Guide with recipes: Hooks.

"hooks": {
  "onToolCall": [
    { "action": "webhook", "url": "https://ops.example.com/audit" },
    { "action": "approve", "tools": ["send_*"] }
  ],
  "onComplete": [{ "action": "save_json", "path": "runs/log.jsonl" }],
  "onError":    [{ "action": "log", "level": "error" }]
}

Buckets (each an array of actions): onStart (run begins) · onToolCall (before each tool — the only bucket that can block) · onToolEnd (after each tool that ran) · onModelCall (before each model call; observe/inject only) · onModelEnd (after each model response — per-call usage/cost/stop-reason/tool-count, the metering moment) · onComplete (every terminal state: end/abort/limits/error, payload carries reason) · onError (unrecoverable failure).

Actions:

Validation is loud: a malformed hook (bad URL, escaping path, approve outside onToolCall, command without opt-in) fails the profile at load — a declared hook never silently doesn't fire. Operator env vars: OWNWARE_DISABLE_HOOKS=1 (kill switch), OWNWARE_HOOK_WEBHOOK_ALLOWLIST=prefix,prefix (restrict webhook egress).

agent.json — subagents

The subagents array is the security boundary: a profile can only spawn what it declares here. Each entry is one of three kinds — an inline spec, a private helper, or a reference to another registered profile.

"subagents": [
  { "name": "researcher", "description": "Finds sources, read-only", "model": "anthropic:claude-haiku-4-5",
    "tools": { "preset": "readonly" } },

  { "name": "auditor", "description": "Runs the security review", "profile": "ownware-security" }
]

See Multi-agent teams for the coordination patterns.

agent.json — metadata

Display-only fields (the profile editor writes to these too). Nothing here affects behavior.

SOUL.md

The system prompt, written as plain markdown — identity, rules, tone, hard constraints. The kernel combines it with the enabled context fragments (git, os, date…) to build the final prompt. If you set systemPrompt inline in agent.json, that is used instead.

You are a concise, careful assistant for my project.
Prefer short answers. Never invent file contents — read the file first.

AGENTS.md — memory

The agent's memory file. When memory.sources includes it (the default), its contents persist into context across conversations — learned preferences, project facts, corrections. With memory.autoLearn: true, the agent may append to it.

skills

A skill is a reusable markdown how-to the agent can invoke — a repeatable workflow (a contract-review procedure, a commit routine) packaged as a file. Skills live in the folders listed by skills.dirs (default skills/).

Each skill is a markdown file with a YAML frontmatter header:

---
name: summarize
description: Summarize a document into a one-page brief with citations
trigger: /summarize
allowedTools:
  - readFile
  - glob
  - grep
---

# Summarize Workflow

Follow these steps.

## Step 1: Read
Read the entire document before writing anything…

The profile skill loader reads exactly name / description / trigger today; trigger is always a literal string. (allowedTools and triggerIsRegex are not yet honored for profile skills — don't rely on them to sandbox a skill.) If a skill's YAML frontmatter is malformed, that skill is skipped with a [ownware] Skipping skill …: invalid YAML frontmatter warning — wrap a description containing a colon in single quotes.

Two layouts are supported: a flat skills/<name>.md, or a nested skills/<slug>/SKILL.md (the nested form can be toggled off with a .disabled marker file). When the trigger matches, the skill's full body is injected as the working instructions for that task. To add a skill, drop a new file in skills/ — no config change needed. A skill can be passed down to a subagent via a subagent grant.skills entry, which inlines it into the child's prompt.

Custom tools

A custom tool is your own logic in a TypeScript/JavaScript file inside the profile, referenced from tools.custom. Each file exports one or more tools built with defineTool:

import { defineTool } from 'ownware'

export const codeReview = defineTool({
  name: 'code_review',
  description: 'Run a code review on a file',
  inputSchema: {
    type: 'object',
    properties: { file: { type: 'string', description: 'File to review' } },
    required: ['file'],
  },
  async execute(input) {
    return { content: 'Review complete', isError: false }
  },
})

Reference it in agent.json — functions is optional (omit to load every exported tool):

"tools": { "custom": [{ "path": "tools/review.ts", "functions": ["codeReview"] }] }

The path must be relative and stay inside the profile directory — absolute paths and .. traversal are rejected (a shared or AI-generated profile is untrusted input). Custom tools get no special trust: every security layer applies to them equally. Restart the gateway after adding one.

helpers — private subagents

A helpers/<name>/ subdirectory holds a full nested profile (its own agent.json, SOUL.md, skills/, custom tools — anything a top-level profile has). These are private to the parent: the global discovery walker never registers them, so only this parent can spawn them.

profiles/ownware-law/
├── agent.json          # declares subagents: [{ name: "researcher", … }]
├── SOUL.md
├── skills/
└── helpers/
    ├── researcher/
    │   ├── agent.json  # "kind": "helper"
    │   └── SOUL.md
    ├── analyst/
    ├── drafter/
    └── checker/

A helper profile typically sets "kind": "helper" (hidden from the lobby, only invokable as a subagent) and often runs a cheaper model:

{
  "name": "legal-researcher",
  "kind": "helper",
  "description": "Legal research specialist. Read-only, exhaustive. Runs on Haiku for speed.",
  "model": "anthropic:claude-haiku-4-5",
  "tools": { "preset": "full", "deny": ["writeFile"] }
}

How a subagent resolves

When a parent spawns a subagent named in its subagents[], the kernel looks it up in this order:

1. helpers/<name>/ in the parent's own directory — a private helper wins first.
2. Else, if the subagent entry has a profile field — that name is looked up in the global registry (this is how one top-level profile becomes another's subagent).
3. Else — the inline subagents[] spec (model, tools, systemPrompt) is used directly.

So any of your profiles can serve as a subagent of another: declare it in the parent's subagents[] with "profile": "<its-name>", or nest it under helpers/ to keep it private. The subagents[] declaration is always required — a parent can never spawn something it didn't list.

See also

• Hooks — the lifecycle-hook guide: all five actions with recipes, the approval flow, the trust model.
• Example profiles — the bundled profiles, read as worked examples.
• Multi-agent teams — coordinating subagents.
• Tools & connectors — MCP, Composio, and custom tools in depth.
• Security overview — levels, zones, and permissions.
• Models — provider:model strings and the keyless path.