Runtime Environment

When you run a .cortex bundle, the Cortex runtime does the following for each agent defined in the manifest:

1. Spawns the agent as an isolated OS process inside a Linux namespace
2. Applies the CPU and RAM limits from the manifest using cgroups
3. Mounts a restricted filesystem — only directories explicitly permitted in capabilities are visible
4. Blocks all outbound network traffic except domains listed in network.access
5. Attaches the agent to the inter-agent message bus
6. Streams structured log output to the Cortex log collector

The agent code sees a normal Python or Node.js environment. The isolation is invisible to it.

---

Resource Isolation

Each agent gets its own resource ceiling. Limits are hard — the process is killed cleanly if it exceeds them, not throttled.

resources:
  cpu_limit: 1.0      # Maximum CPU cores (fractional values allowed)
  mem_limit: 2Gi      # Maximum RAM (Mi or Gi)

If you omit resources, the agent inherits the project-level defaults. If no project defaults are set, the Cortex daemon's own configured limits apply.

---

Capability Model

Nothing is permitted by default. Every external resource the agent needs must be declared.

Capability	What it grants
network.access: ["domain"]	Outbound HTTP/HTTPS to the listed domains only
filesystem.read: ["./path"]	Read access to the listed directory
filesystem.write: ["./path"]	Write access to the listed directory
observability.metrics: true	Emits agent metrics to the Cortex metrics endpoint
security.logging: strict	Forces structured JSON log output, no raw stdout

Capability checks are enforced at the OS level via seccomp/namespace rules — not in userspace. An agent cannot work around them by spawning subprocesses.

---

Process Lifecycle

State	Description
starting	Process is being provisioned
running	Agent is active and processing
suspended	Agent is paused (state preserved in memory)
stopped	Agent has exited cleanly
failed	Agent exited with a non-zero code

Control lifecycle from the CLI:

cortex list                     # See all agents and their states
cortex kill assistant           # Stop a running agent
cortex logs --follow assistant  # Stream logs from a specific agent

---

Inter-Agent Communication

Agents in the same swarm communicate via a local message bus. Messages are published to named channels and consumed asynchronously.

# Agent A — publish a result
from cortex.bus import publish
publish(channel="analysis-results", payload={"status": "done", "score": 0.94})

# Agent B — subscribe and react
from cortex.bus import subscribe
for message in subscribe("analysis-results"):
    print(message["score"])

Agents on different nodes cannot communicate by default. Configure a shared broker (e.g., Redis Pub/Sub) in global_capabilities for cross-node communication.

---

Integration with ICE

If you're using ICE for agent memory, inject the ICE URL and identity headers via environment variables in the manifest:

agents:
  - name: assistant
    runtime: python3.11
    entrypoint: agent:run
    env:
      ICE_URL: "http://ice-kernel:8000"
      CORTEX_SESSION_ID: "project-alpha"
      CORTEX_USER_ID: "user-alice"
    capabilities:
      - network.access: ["ice-kernel"]

The agent reads these at runtime and passes them as headers on ICE requests. Cortex does not manage the ICE connection — it simply provides the environment.