# Glossary

> The words OpenEng uses, defined in one place, starting with the ones that are easy to mix up: connector vs cell vs integration, model role vs behavioral role, loop strategy vs global loop, engine vs surface vs config, the Console vs the Web Console, and the different keys and sandboxes.

OpenEng is one platform with two halves, the engineering apps and OpenEng AI, and a few words are
used on both sides with different meanings. The first section untangles the pairs people mix up; the
rest of the page defines the other terms from A to Z.

## Words that are easy to mix up

### Connector, cell and integration

All three let OpenEng reach something outside your machine, but they belong to different products.

| Aspect | Connector | Cell | Integration |
| --- | --- | --- | --- |
| Used by | The engineering apps: Terminal, Kubernetes and Data | OpenEng AI | OpenEng AI |
| What it is | Pure-Python source you deploy as a function in your own cloud account, behind an API-key gateway | The same kind of function, in your own cloud account | A definition pointing at a remote https endpoint with a declared (unverified) sandbox tier; its code doesn't run on your machine |
| Scope | Usually one cloud service or data system with a few tools; the Kubernetes connector carries about 150 | One cloud service and a handful of tools | One service: GitHub, GitLab, Jira, Canva, ElevenLabs, Datadog or Kubernetes |
| Catalog | [connectors.openeng.app](https://connectors.openeng.app) | [cells.openeng.app](https://cells.openeng.app) | The [integrations list](https://connectors.openeng.app/integrations) on connectors.openeng.app |
| Where you add it | In the app | Console → Connect → **Cells** | Console → Connect → **Connectors** |
| Docs | [Connectors](connectors.md) | [Cells](cells.md) | [Integrations](integrations.md) |

Connectors and cells speak the same small protocol over HTTPS (`/healthz`, `/manifest`, `/tools`,
`/call`). The Console's page for integrations is named **Connectors**; these docs call them
*integrations* so they aren't confused with the engineering apps' connectors.

### Model role and behavioral role

- A **model role** is one of the eleven slots the AI engine routes its calls through, such as
  `planner`, `agent`, `reviewer` or `summarizer`. A config binds a model to each role group in its
  Models step ([Models & role defaults](models.md#role-models)).
- A **behavioral role** is a `role_def_*` rule-set from [roles.openeng.app](https://roles.openeng.app):
  a task flow, constraints, an output contract and quality gates that make an agent, delegator or
  sub-agent work like a named professional. It steers how a component works and never grants it tools.
  You attach behavioral roles on Console → Govern → **Roles** ([Roles](roles.md)).

### Loop strategy and global loop

- A **loop strategy** (iteration strategy) is how the engine runs a single turn: how it observes,
  acts, reviews, plans and retries. The engine picks one for every request, and a config can constrain
  the choice ([Iteration strategies](loops.md#iteration-strategies)).
- A **global loop** is a loop you define and start, such as "work through my open tickets until none
  are left": a request, a source of iterations and a stopping rule. Each iteration is a full turn
  ([Global loops](loops.md#global-loops)).

### Engine, surface and config

- An **engine** is the native program on your machine that does the work. Each engineering app has its
  own engine (`openeng-terminal`, `openeng-kubernetes`, …) that listens on a loopback port; OpenEng AI
  has one engine, `openeng`, which opens no port and dials out to the Broker
  ([How OpenEng works](architecture.md)).
- A **surface** is a web app you use in the browser: one of the five engineering apps, the Console, the
  Web Console or the billing site. A surface shows things and sends your requests; the work happens in
  an engine.
- A **config** is a versioned bundle you build in the Console and publish: which models serve which
  roles, which agents, skills, cells and other items are available, and the limits and settings. The AI
  engine runs published configs ([Configs](configs.md)). The engineering apps have no configs; each
  app's settings live with its engine on your machine.

### The Console and the Web Console

- The **Console**, at [console.openeng.app](https://console.openeng.app), is where you author: models,
  agents, templates, connections, guardrails and configs, and where you publish ([The Console](console.md)).
- The **Web Console**, at [app.openeng.app](https://app.openeng.app), is where you use OpenEng AI: pick
  an engine and a published config, then chat and run work on your engine
  ([Open the Web Console](ai-getting-started.md#6-open-the-web-console)).

### Keys

| Key | What it's for | Where it comes from |
| --- | --- | --- |
| **One-time key** | Starting an engineering app's engine: `openeng-terminal serve --oauth=<one-time key>` | The app's pairing screen. It works once and expires after about five minutes ([Pairing](architecture.md#pairing)). |
| **OpenEng key** | Starting the AI engine: `openeng serve --key=<key>` or `OPENENG_KEY` | Console → Deploy → **API keys**; shown once ([The engine](engine.md#start)) |
| **API key** | The same thing as an OpenEng key; also what headless and sandbox machines use | Console → Deploy → **API keys** ([API keys & sandboxes](api-keys-sandboxes.md)) |
| **Write key** | Letting a connector make changes; without it a connector is read-only | [connectors.openeng.app/write-key](https://connectors.openeng.app/write-key) ([Connectors](connectors.md#read-only-by-default-per-request-write-key)) |

A connector's or cell's own **API key** is something else again: a key you issue in your cloud's API
gateway. The engineering apps' engines send a [connector](connectors.md)'s key as the `x-api-key`
header; the AI engine sends a [cell](cells.md)'s key as `Authorization: Bearer <key>`.

### Sandbox

- A **sandbox node** is a machine registered to your account's fleet on Console → Deploy →
  **Sandboxes**; the current engine can't register a node yet
  ([API keys & sandboxes](api-keys-sandboxes.md)).
- The engine's **OS sandbox** confines the shell commands its agents run. When bubblewrap works on
  the machine (Linux; Seatbelt plays that part on macOS, but there is no macOS AI engine build yet), by
  default they can write only inside the working directory;
  otherwise shell commands run unconfined (`OPENENG_SANDBOX`; [The engine](engine.md#environment)).
  Local models also run only inside a sandbox ([Local models need a sandbox](engine.md#local-model-sandbox)).
- An integration's **sandbox tier** (`tier2Jail` or `tier3Microvm`) is a field its author fills in to
  declare how isolated the remote endpoint it points at is; the engine can't verify it
  ([Integrations](integrations.md)).

## A to Z

**Agent.** A reusable persona: a system prompt, optionally its own model, plus delegation, caps and
tool grants. The catalog has single agents and orchestrators that delegate to sub-agents
([Agents](agents.md)).

**Broker.** The OpenEng service the AI engine dials out to. It opens your Web Console requests to route
them to your engine, relays the engine's streamed replies (sealed end to end to your browser when the
request carries a usable browser key), opens
and delivers the engine data the Web Console loads, and keeps every envelope it routes for 7 days by
default ([Transport security](security.md#ai-transport)).

**Catalog.** A public list of ready-made items with its own site, such as
[skills.openeng.app](https://skills.openeng.app), and a `catalog.json` file
([Catalogs & IDs](catalogs.md)).

**Cloud Planner.** An option for the planner role that runs on OpenEng's planning credit instead of an
API key of your own; its requests go through `api.openeng.app` to Gemini on Vertex AI
([Plans & billing](account.md#planning-credit)).

**Complexity analysis.** The engine's first step on every request: it scores how complex the request
is and either answers directly or plans a multi-step run ([Loops](loops.md)).

**Default config.** The config the AI engine uses for requests that don't name one, set with
`--default`, `OPENENG_DEFAULT_CONFIG`, or your account's config named `default`, otherwise the first
config you own ([Which config the engine serves](engine.md#config-selection)).

**Device Use.** A vision model that looks at the screen and clicks and types to finish a goal, bound in
a config's Models step ([Configs](configs.md#models-step)). It needs an engine build with the X11
device backend, which the published Linux x86_64 engine doesn't include yet.

**Engine pairing.** How an engineering app connects to its engine: you sign in, the app gives you a
start command with a one-time key, and the app connects when the engine starts
([Getting started](getting-started.md#start-and-connect)).

**engine.openeng.app.** A public name that points at `127.0.0.1`. The engineering apps reach their
engines at `https://engine.openeng.app:<port>`, so the browser gets a trusted HTTPS connection to your
own machine ([A sealed transport](architecture.md#sealed-transport)).

**Execution flow.** The graph of stages a config's runs go through, with presets you can start from
([Execution flow](execution-flow.md)).

**Gateway floor.** The policies every call on your machine passes through, which are always on and
can't be edited: secret egress, secret redaction, authorization, envelope checks and metering
([Security](security.md#the-always-on-gateway-floor)).

**Human-in-the-Loop.** Rules that pause a run until a person approves it, at a boundary such as an
agent, an MCP server, a model, a worker action or a cell. Managed on Console → Govern →
**Human-in-the-Loop** ([Human-in-the-Loop](human-in-the-loop.md)).

**Library.** A themed bundle of agents, skills, templates and cells that you import into a config as
one unit ([Library](library.md)).

**MCP server.** A tool server that speaks the Model Context Protocol, which your agents can call
([MCP](mcp.md)).

**Placeholder.** An `${ENV_VAR}` name that stands in for a secret everywhere in the Console; the value
is resolved on your engine ([Secrets](security.md#secrets-env-placeholders-end-to-end)).

**Plugin.** A behavior at the engine's gateway that gates, transforms, observes or enriches calls
([Plugins](plugins.md)).

**Publish.** Freezing the current state of a config as a new version the engine can run. A published
version never changes ([Configs](configs.md#publishing)).

**Scheduler.** A prompt meant to run on a schedule written in five-field cron; the published engine
doesn't fire schedules yet ([Schedulers](schedulers.md)).

**Sealed channel.** The encryption on a session's frames between an engineering app and its engine, on top of
HTTPS (X25519, HKDF-SHA256, ChaCha20-Poly1305) ([A sealed transport](architecture.md#sealed-transport)).

**Skill.** A focused playbook the engine adds to a turn so the model works the way it describes
([Skills](skills.md)).

**Storage point.** A destination for run results, such as a GitHub repository, an S3 or Google Cloud
Storage bucket, a Google Drive folder or a WebDAV server; the engine doesn't deliver to them yet
([Storage points](storage-points.md)).

**Template.** A prompt set: a system prompt the engine combines with your prompt
([Templates](templates.md)).

**Token limit.** A budget on token use, set on Console → Govern → **Token limits** ([Govern](govern.md)).

**`_def_` and `_usr_` ids.** A `_def_` id is a shipped default from a catalog; a `_usr_` id is an item
in your own account ([IDs](catalogs.md#ids)).