cortex.yaml Reference

The cortex.yaml file defines every agent in your swarm — what it runs, what it's allowed to do, and how many resources it can use.

Full Example

version: "1"
project: my-agent-swarm

# Project-level defaults applied to all agents unless overridden
defaults:
  runtime: python3.11
  resources:
    cpu_limit: 0.5
    mem_limit: 512Mi
  restart_policy: on-failure
  max_restarts: 3

global_capabilities:
  - observability.metrics: true
  - security.logging: strict

agents:
  - name: researcher
    description: Fetches and summarises external documents.
    entrypoint: agents.researcher:main
    resources:
      cpu_limit: 1.0
      mem_limit: 2Gi
    capabilities:
      - network.access: ["api.openai.com", "api.dopove.com", "arxiv.org"]
      - filesystem.read: ["./data"]
    env:
      LOG_LEVEL: INFO
      ICE_URL: "http://ice-kernel:8000"

  - name: writer
    description: Takes researcher output and produces final reports.
    entrypoint: agents.writer:main
    capabilities:
      - network.access: ["api.openai.com"]
      - filesystem.read: ["./data"]
      - filesystem.write: ["./output"]
    env:
      LOG_LEVEL: INFO

---

Schema Reference

Root Fields

Field	Type	Required	Description
version	string	Yes	Manifest schema version. Currently "1".
project	string	Yes	Unique name for this swarm. Used in logs and CLI output.
defaults	object	No	Default values applied to all agents unless overridden.
global_capabilities	list	No	Capabilities inherited by all agents.
agents	list	Yes	List of agent definitions.

---

Agent Fields

Field	Type	Required	Description
name	string	Yes	Unique agent identifier within the project.
description	string	No	Human-readable description. Shown in cortex list.
runtime	string	Yes	Execution environment: python3.10, python3.11, python3.12, nodejs18, nodejs20.
entrypoint	string	Yes	Module path to the agent entry function (e.g., agent:run or agents.worker:main).
resources	object	No	CPU and RAM limits. Inherits from defaults if omitted.
capabilities	list	No	Explicit permission grants. Nothing is allowed unless declared.
env	map	No	Environment variables injected into the agent process.
restart_policy	string	No	always, on-failure, or never. Default: never.
max_restarts	integer	No	Maximum restart attempts before the agent is marked failed.

---

Resources

resources:
  cpu_limit: 1.0    # Cores. Fractional values supported (e.g., 0.5)
  mem_limit: 2Gi    # RAM. Accepts Mi or Gi suffix.

Limits are enforced via Linux cgroups. If an agent exceeds its memory limit it is terminated immediately.

---

Capabilities

Capability	Example value	Effect
network.access	["api.openai.com"]	Allow outbound HTTPS to listed domains only
filesystem.read	["./data"]	Allow read access to listed paths
filesystem.write	["./output"]	Allow write access to listed paths
observability.metrics	true	Emit agent metrics to Cortex metrics endpoint
security.logging	strict	Force structured JSON log output

Capability checks are enforced at the kernel level. An agent cannot bypass them by spawning subprocesses or using syscalls directly.