# Integrations

> Integrations are the Console's Connect → Connectors page: remote services with a declared sandbox tier, such as GitHub, GitLab, Jira, Canva, ElevenLabs, Datadog and Kubernetes, that your agents are meant to call. An integration never runs on your machine; the engine only dials its https endpoint. Integration calls don't work yet: the catalog's endpoints return a web page instead of JSON, and the engine sends no credential. As of September 25, 2026, OpenEng AI isn't live yet.

**Integrations** are what the Console's **Connect → Connectors** page manages:
remote services such as GitHub, GitLab, Jira, Canva, ElevenLabs, Datadog and
Kubernetes, each with a declared sandbox tier, that your agents are meant to
call (their calls don't work yet; see [below](#use-in-a-config)). The Console calls
them *connectors*; these docs call them *integrations* so they aren't confused
with the engineering apps' [connectors](connectors.md), which are functions you
deploy into your own cloud for Terminal, Kubernetes and Data.

> [!WARNING] Status on September 25, 2026: OpenEng AI isn't live yet
> The Console and Web Console interfaces load, but the OpenEng AI API routes and the Broker aren't
> deployed. Nothing can be saved or published, and no AI engine can register or connect. Pro,
> Enterprise and pay-as-you-go launch in Q4 2026 and can't be purchased yet. This page describes
> OpenEng AI as it works once those services are live ([status](ai.md)).

*Figure: Connect → Connectors — your integrations and the catalog; each is a remote https endpoint with a declared host-isolated sandbox tier, edited in a slide-over and picked per config in the builder.*

## What an integration is

An integration is a definition that points at a **remote `https://`
endpoint**. The engine on your machine only *dials* that endpoint; the
integration's code never runs on your machine. Every definition also names a
declared **host-isolated sandbox tier**, **Tier 2 · jail** (`tier2Jail`) or
**Tier 3 · micro-VM** (`tier3Microvm`), for where the endpoint runs. The tier
is a field the definition's author fills in: the engine checks the label, the
`https://` scheme and that the endpoint isn't a private address, but it can't
verify how a remote host is isolated. The catalog's entries point at
OpenEng-hosted endpoints under `connectors.openeng.app/fn/`, so the tool
arguments your agents send them would go to OpenEng.

This rule, *sandbox-only*, is enforced three times: the Console's editor
refuses a definition that breaks it, the API refuses it when you save, and the
engine rejects it when it loads the config.

| Aspect | Integration | [Cell](cells.md) | [MCP server](mcp.md) |
|---|---|---|---|
| Runs | a remote, host-isolated endpoint | inside your own cloud account | on or near your machine, or any HTTP host |
| You deploy it | no, the definition points at an endpoint | yes, into your cloud | stdio servers run locally; HTTP servers anywhere |
| Transport | https only | https (plain http only to loopback) | stdio or HTTP |

The [glossary](glossary.md#connector-cell-integration) sets connectors, cells
and integrations side by side.

## The catalog

The shipped integrations are published at
[connectors.openeng.app/integrations](https://connectors.openeng.app/integrations)
(machine-readable at `https://connectors.openeng.app/integrations/catalog.json`).
As of 2026-09-25 the catalog has seven:

| Integration | Category | Tools | Sign-in methods | Tier |
|---|---|---|---|---|
| GitHub | Source Control | 5: repositories, issues, pull requests, Actions runs and logs | OAuth, API key | Tier 2 |
| GitLab | Source Control | 6: projects, issues, merge requests, pipelines, jobs, job traces | OAuth, API key | Tier 2 |
| Jira | Project Management | 5: issue search, issues, comments, sprints, boards | OAuth, API key | Tier 2 |
| Canva | Design | 4: designs, a design, assets, export URLs | OAuth | Tier 2 |
| ElevenLabs | Media & Voice | 4: voices, models, text-to-speech, history | API key | Tier 2 |
| Datadog | Observability | 3: metrics query, monitors, log search | API key | Tier 3 |
| Kubernetes | Infrastructure | 5: pods, pod logs, deployments, events, rollout status | API key | Tier 2 |

The catalog tools are read-oriented (list, get, search, query), plus
ElevenLabs' speech synthesis.

## The Connectors page: Mine and Catalog

The page has two tabs:

- **Catalog** — the shipped integrations, read-only. **Use** adopts one into
  your collection in a single click; **Customize** opens a copy in the editor
  first, under a fresh id you can edit and version.
- **Mine** — your own integrations, adopted or written from scratch, listed
  with name, endpoint, sandbox tier, credential placeholder and tool count.
  Rows carry **Versions**, **Edit** and **Delete** (delete behind a
  confirmation; published config versions keep their frozen copy).

**New** opens an empty editor. Copies that the config builder pins to a
config are listed separately under **Pinned to configs**, never mixed into
your list.

## Create or customize an integration

The editor is a slide-over with these fields:

| Field | What it holds |
|---|---|
| **Name** | Required, e.g. `GitHub` |
| **Slug** | A stable machine name; defaults to the id |
| **Version** | e.g. `1.0.0` |
| **Endpoint URL** | Required; `https://` only |
| **Sandbox tier** | Tier 2 · jail or Tier 3 · micro-VM |
| **Credential** | A `${ENV_VAR}` placeholder, never a value |
| **Category**, **Summary** | Shown in the list |
| **Tools** | The tool names the endpoint exposes; for information only, since the engine discovers tools itself |
| **Auth methods** | For information, e.g. `oauth`, `api_key` |
| **Info** | Longer notes |

Like every Console editor, it saves only when you press **Save**. There is no
connection test: the Console stores configuration only, and the engine checks
connectivity when it serves a config that uses the integration.

## Use it in a config

A config uses the integrations you pick in the config builder's
**Connectors** step ([Configs](configs.md#components)); the step lists only
your own integrations, so adopt a catalog entry first. Publish the config.

When the engine serves it, it admits the config's integrations that pass the
sandbox-only rule and logs, for example,
`connectors registry — 2 admitted, 0 rejected (sandbox-only)`. A rejected
definition never reaches your agents; the reason reads like
`connector '<id>' rejected: transport must be an https:// remote endpoint`.

When an agent calls an integration's tool, the engine sends an https `POST`
to the endpoint URL plus the tool name, with the arguments as JSON. It
refuses endpoints that resolve to private or internal network addresses, and
gives each call 30 seconds (10 seconds to connect). The call passes the
engine's gateway like every other resource, so [plugins](plugins.md) on the
connector gateway can gate or observe it.

> [!WARNING] Integration calls don't work yet
> Two things limit integrations in the current release. The catalog entries
> point at endpoints under `https://connectors.openeng.app/fn/`, which return a
> web page instead of JSON (checked 2026-09-25). And the engine doesn't send the
> credential you store with a definition yet; calls carry only the tool
> arguments. Once the OpenEng AI services are live ([status](ai.md)), you can
> author, adopt and publish integrations on every plan; calling them needs an
> endpoint that answers.

## Plan & tier notes

The Connectors page is open on **every plan**. Running a config needs the
`openeng` engine, which registers only with an active **Pro** plan; Pro
launches in Q4 2026 and can't be purchased yet
([Plans & billing](account.md#ai-pricing)).

## Troubleshooting

**"The sandbox tier must be tier2Jail or tier3Microvm."** Pick one of the two
host-isolated tiers; lower tiers would run on your machine and are never
allowed.

**The editor refuses the URL.** It must parse and start with `https://`.

**The builder's Connectors step is empty.** It lists only your own
integrations. Adopt one on the Catalog tab (or create one), then return to the
step.

**The engine log shows `rejected (sandbox-only)`.** A definition in the
config breaks the rule (not https, or a tier below Tier 2). Fix it on the
Connectors page and publish a new version.

**A tool call fails with `connector … decode: …`.** The catalog endpoints
return a web page instead of JSON, so the engine can't decode the answer. See
the warning above. A `connector … → HTTP 404` (or another status) means the
endpoint answered with an error, for example because it doesn't serve that tool.