Concepts

openma has nine core concepts. Skim this page once and most of the docs will make sense. Each section ends with a link to where the concept is used in depth.

Agent

A reusable configuration that defines what model to call, what system prompt to use, what tools and skills are available, and which MCP servers to connect. Agents are versioned: every update creates a new version, so a session always pins the version it was created with.

Stored through the configured database adapter; mutated through the Console (Agents page) or the /v1/agents REST endpoint. See the Configuration reference.

Session

A single conversation with an append-only event log of model messages, tool calls, results, and lifecycle events. Cloudflare uses Durable Objects; Node uses SQL storage. Committed history lets clients reconstruct conversations after reconnecting and lets the runtime resume from persisted state.

Created via POST /v1/sessions. Stream events with GET /v1/sessions/:id/events (Server-Sent Events). Detailed API in REST API.

Note

The event log is the source of truth. The Console UI, the SSE stream, and any future replay tooling all read the same log.

The OpenAI API presents the same native facts as Turns (units of execution) and Items (messages, tool calls, and results). Subagents have separate histories and share the parent environment. The current Node OpenAI execution path allows the main agent to delegate one level deep.

Environment

The sandbox configuration: which packages to install (pip, npm, apt, cargo, gem, go), networking rules, and which container image to run. When a session needs to execute code (via the bash tool, custom tools, or harness logic), the selected runtime prepares a local or remote sandbox based on this environment. OpenAI sessions can also select environment: { type: "none" } for text and client function tools without allocating a physical sandbox.

Manage on the Console Environments page or via /v1/environments.

Vault

A credential store. Vaults hold bearer tokens, OAuth tokens, and env vars that tools and integrations need.

The platform’s credential-isolation property: secrets never leave the main worker. Both the agent (cloud DO or local daemon) and the sandbox container only know (tenantId, sessionId, server-name | hostname) — they ask main to make the actual upstream call. Main looks up the credential live (no per-session snapshot), injects the bearer, and forwards. A prompt-injected agent has no credential to leak because there isn’t one in its address space.

For OAuth credentials (mcp_oauth type), the platform also handles 401-triggered refresh automatically and persists the rotated tokens back to the vault — sessions survive token rollovers without intervention. Concurrent refresh dedup via D1 re-fetch keeps rotating-refresh-token providers (Linear, Notion) from invalidating themselves under concurrent load.

Vaults are managed in the Console (Vaults page) and via /v1/vaults. Bound to specific hosts so a leaked or hostile tool can’t pivot. Full architecture: Vault & MCP Credentials.

Caution

Anything sensitive belongs in a Vault. Never put secrets in an Agent’s system prompt or in tool inputs.

Memory Store

Persistent named files shared across sessions. Attach a store with read_only or read_write access; agents use ordinary file tools at /mnt/memory/<store_name>/. There is no dedicated memory tool. Writable mounts require a runtime with reverse synchronization; the current Node managed runner accepts read-only mounts. See Memory Stores for write-back, conflicts, version history, and deployment limits.

Manage on the Console Memory page or via /v1/memory_stores.

Skill

A reusable prompt fragment plus optional files mounted into the sandbox. Two kinds:

• Built-in skills — handlers for xlsx, pdf, docx, pptx, json, csv, sql, image, etc.
• Custom skills — your own. Metadata in D1, files in R2. The platform mounts the files at /home/user/.skills/{id}/ and injects a system prompt addition that points the model at them.

Manage on the Console Skills page or via /v1/skills. See Skills & Tools.

Tool

Anything the model can call. Three shapes:

• Built-in tools — bash, read, write, edit, glob, grep, web_fetch, web_search. Shipped as the agent_toolset_20260401 toolset.
• Custom tools — defined inline on an Agent with a JSON schema; the platform routes calls to your endpoint or executes them in the sandbox.
• MCP tools — connect any MCP server and the platform auto-generates mcp_* tools.

Detailed schemas in Skills & Tools.

Harness

The agent loop itself — the code that decides what the model does next given the session events. openma owns the loop and ships three placements behind the same harness interface:

• DefaultHarness / PiHarness — run the loop in the OpenMA host.
• ACP sandbox harness — spawn an ACP-compatible agent such as Claude Code or Codex inside the session sandbox while OpenMA keeps ownership of session lifecycle and canonical events.
• ACP proxy harness — use a user-registered local runtime when the agent must run on a particular device.

You can also register a custom harness that:

• Drives a different model loop
• Handles compaction differently (shouldCompact, compact)
• Customizes the system prompt assembly (deriveModelContext)
• Hooks into session lifecycle (onSessionInit, run)

Compaction is a required harness capability, not provider behavior. PiHarness ships with a Pi-native policy that triggers from the model context window, summarizes through the tenant-scoped pi-ai model runtime, persists one agent.thread_context_compacted boundary, and performs one bounded compact-and-retry when Pi identifies a provider context-overflow response. The default cc-style policy uses an isolated summary-only payload with no tools and no image bytes. The explicit summarize policy instead preserves the active system/tools/history prefix and adds its instruction at the tail so automatic provider prefix caches remain eligible during the summary call. Replacing old history with the summary still creates one intentionally cold main-model boundary; later turns append to that stable compacted prefix and become cacheable again. The policy is replaceable without replacing the model/tool loop:

import { PiHarness } from '@open-managed-agents/agent/harness/pi-loop';
import type { PiCompactionPolicy } from '@open-managed-agents/agent/harness/pi-compaction';

const policy: PiCompactionPolicy = {
  name: 'my-policy',
  shouldCompact: (_events, { messages, contextWindowTokens }) =>
    estimate(messages) > contextWindowTokens - 16_000,
  async compact(events, context) {
    // Use context.models/context.model, another model, or a deterministic reducer.
    return summarize(events, context);
  },
};

const harness = new PiHarness({ compaction: policy });

The capability cannot be disabled. A policy may choose not to compact a given turn, but it must remain present so overflow recovery and canonical history semantics do not depend on pi-agent-core internals.

The sandbox placement is provider-neutral: every ACP process uses the SandboxDuplexProcessPort, whether the backing runtime is a Cloudflare Container, a local subprocess, or E2B. Stateful ACP sessions retain one child across turns, renew the provider lease during a turn, and persist the native ACP session id in the workspace so a restored sandbox can resume it.

Integration

A way to publish an Agent into a third-party platform so users interact with it where they already work. Three integrations ship today:

• Linear — agents become workspace members, assignable to issues and mentionable in comments.
• GitHub — agents act on PRs, repos, and issues.
• Slack — agents in channels and threads.

Each integration handles its own OAuth flow, webhook delivery, and exposes its capabilities to the agent as MCP tools. Add your own by implementing IntegrationProvider (see Custom Integrations).

---

Where these live in the code

If you’re reading the source, here’s the rough mapping:

Concept	Source
Agent / Session / etc. types	packages/api-types
REST endpoints	apps/main/src
Session DO + sandbox	apps/agent/src
Harness interface	apps/agent/src/harness/interface.ts
Built-in skills	apps/agent/src/harness/skills.ts
Integrations core	packages/integrations-core
Linear / GitHub / Slack	apps/integrations/src/routes/{linear,github,slack}

Configuration reference Schemas for Agent, Environment, Skill, Vault, and friends.

Glossary Every term, alphabetized, with cross-links.