Connect your AI system.

Getting started

OPERE supplies operating environments for AI systems. Your AI retains task ownership: it requests conditions, produces a candidate and decides how to continue after checks. People authorize reusable boundaries and inspect the same operating state.

Start with a reachable OPERE host, an active scoped machine identity, the configured private model, the restricted-container executor and a running formation worker. An API can retain queued requests while its worker is offline. The walkthrough is illustrative and needs none of these services.

Authentication and ownership

Environment reads, mutations and events require machine bearer authentication. Keep the token in your machine client’s secret store. Never place it in a URL, browser form, source example or contact draft. This documentation includes no credential.

The local operator can run node scripts/connect-formation.mjs to create or validate a private credential file and obtain a separate one-use browser inspection code. Existing grants are not expanded. A remote AI needs a reachable deployment; 127.0.0.1 refers to the calling machine. Use TLS outside loopback.

Read-only browser pairing is separate from machine access and owner management. Neither pairing nor tool discovery grants permission to act. Even another principal in the same tenant cannot inspect your environment.

Outcome: request operating conditions

POST /api/v3/environments with Content-Type: application/json and your machine Authorization header. This example is the registered invoice-function repair: the exact source identity, path and media type matter. Replace the example idempotency key for each new request.

HTTP 202 returns an environment snapshot with formation queued. Inspect fresh state with GET /api/v3/environments/{id}; do not treat admission as readiness or task completion. Unknown input fields are rejected.

{
  "entry": "outcome",
  "outcome": "Repair invoice totals for quantities and rounding.",
  "sources": [
    {
      "id": "invoice-source",
      "name": "src/invoice.js",
      "mediaType": "text/javascript",
      "content": "export function calculateTotal(items) { return items.reduce((sum, item) => sum + item.unitPrice, 0); }"
    }
  ],
  "leaseSeconds": 1800,
  "idempotencyKey": "docs-outcome-unique-key"
}

Observe: start from authorized context

Observe uses an observation summary and supplied sources instead of requiring a typed outcome. It is bounded source intake, not continuous device sensing. This example fits the JSON facts-report domain. Sources must use the registered facts/items structure; arbitrary PDFs and Word documents are not supported.

For an existing environment, POST /api/v3/environments/{id}/observations with expectedRevision, a new idempotencyKey and observation. This replaces source context and queues formation. Current invalidation is conservative: changed context makes prior artifact proof and acceptance stale.

{
  "entry": "observe",
  "observation": {
    "summary": "Produce a source-cited report of these facts.",
    "sources": [
      {
        "id": "monthly-facts",
        "name": "facts.json",
        "mediaType": "application/json",
        "content": "{\"facts\":{\"month\":\"October\",\"invoices\":3},\"items\":[{\"quantity\":2,\"unitPrice\":12.5}]}"
      }
    ]
  },
  "leaseSeconds": 1800,
  "idempotencyKey": "docs-observe-unique-key"
}

Work, verify, accept and release

When conditions are ready, POST actions with operation begin_work or read_context. Both require expectedRevision and idempotencyKey; even read_context consumes an operation and writes an event. Use GET for an unmutating inspection.

POST artifacts with the mutation guard, current contextVersion, name, mediaType and string content. Submission queues independent verification. Current executors verify application/json payloads only: a coding files array replacing src/invoice.js, or a complete facts/report object with exact source hashes and canonical report rendering.

Read every returned check, artifact hash and stale flag. Passing the registered checks supports only that bounded computation and lineage. POST accept requires artifactId, current contextVersion and the mutation guard. It acknowledges the current passed artifact; readiness alone cannot satisfy it.

POST release with the guard to request cleanup. Wait for released before claiming resources are released. History, source context, artifacts and evidence remain retained. Release does not erase records or stop the shared model service or VM.

Errors and recovery

HTTP errors use {error: {code, message}}. A completed 202 can later become blocked in the environment; inspect blockers and their retryable flags. Fix the underlying context, authority or runtime before requesting a bounded retry. There is no simulated or host-execution fallback.

• 400 invalid_input / invalid_sources: correct the JSON shape, safe text or source constraints. 413: reduce the serialized body; v3 HTTP transport is capped at 64 KiB. 415: send application/json.
• 401: obtain an active machine identity from the operator. 403: check capability, byte and operation grants; model inference cannot expand them.
• 404 environment_not_found: verify the ID and owning principal. A non-owned record is intentionally not disclosed.
• 409 revision_conflict: GET fresh state and reassess before a new mutation. stale_context: regenerate against current context. acceptance_denied: inspect the latest artifact and current passing checks.
• 409 idempotency_conflict: a key was reused with a different serialized request. Reuse a key only for an exact retry; after replay, fetch fresh state.
• 503: inspect runtime configuration, capacity or event-history availability. retry is permitted only for a blocked environment with a retryable blocker; retry does not reset inference-call limits.

Events and client compatibility

GET /api/v3/environments/{id}/events?after=0 returns bounded JSON replay with events and a cursor. The cursor is an exclusive revision: resume from the last actually received revision. Accept: text/event-stream selects the separate authenticated API feed.

SSE frames use event: environment and a numeric revision ID. Each response is bounded by 25 seconds, 100 events and 1 MiB, with three streams per principal. Handle closure and event: error. A browser’s native EventSource cannot set the required machine bearer header.

The current MCP bridge uses MCP 2025-11-25 over POST /api/mcp with stateless JSON responses. Initialize, send notifications/initialized, then tools/list or tools/call. Send MCP-Protocol-Version after initialization. Inspect JSON-RPC errors and result.isError even with HTTP 200. The bridge has no MCP GET/SSE stream, persistent session, sampling or asynchronous task feature. These are this bridge’s limits, not limits of MCP generally.