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 in D1; mutated through the Console (Agents page) or the /v1/agents REST endpoint. See the Configuration reference.

Session

A single conversation. Sessions are durable — backed by a Cloudflare Durable Object with a per-session SQLite database that holds the append-only event log: every model message, tool call, tool result, and lifecycle event. You can resume a session days later and the platform replays the events.

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.

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 platform spins up a Cloudflare Container based on this environment.

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

Per-agent semantic memory across sessions. Memory entries are embedded with Workers AI and indexed in Vectorize. The agent can recall earlier conversations or facts via a built-in memory tool.

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, LiteBox, 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.