i2x
Public integration guide

One governed workflow, from any supported client.

Connect Codex or Claude through MCP, or integrate an application or CI workflow through the authenticated HTTPS API. This guide documents the customer-visible contract only.

Same contract everywhere

How a governed request moves

01 CONNECTCreate a revocable workspace connection.
02 REQUESTBind work to a project and exact source.
03 CLAIMThe agent receives one bounded task.
04 RETURNSubmit required structured outputs.
05 INSPECTRead status, limitations, and evidence.

What runs where

How you startWhere Codex or Claude runsWhat i2x receivesWhat you get back
Local folderOn your Windows, macOS, or Linux computer through the official client.A scoped task response and declared project observations—not your provider login.A readable project record, labelled agent findings, and the checks or approvals still required.
Repository or CIIn the runner or CI worker selected for the exact repository revision.The source identity, bounded check results, provenance, and limitations permitted by that connection.A machine-readable status plus a human-readable receipt tied to the exact source.
Your app or automationIn the agent or service your product already uses; i2x is called through HTTPS.The project-scoped request and required structured return—never unspecified authority.The same governed result contract for display in your own interface.

Source access is chosen separately. Keeping code local, granting repository access, or sending a bounded evidence package are different configurations. The interface must show the selected configuration before a job starts.

The agent still reasons. i2x defines the task boundary, permitted operations, required output contract, and approval gates. The connection itself never grants release or recovery authority.

Connect Codex or Claude

Create a provider-specific connector in the i2x workspace. Its secret is workspace-scoped and revocable. Add the returned MCP configuration to the official client, start the client, then complete the one-time connector.prove challenge.

[mcp_servers.i2x]
command = "node"
args = ["i2x-mcp"]

[mcp_servers.i2x.env]
I2X_CONNECTOR_TOKEN = "<token shown once by i2x>"

A successful proof establishes that the scoped connector completed a round trip. It does not prove the provider subscription tier or remaining allowance, and the provider login is not sent to i2x.

Authenticated HTTPS API

The web application, local runner, and CI integrations use the same authenticated API contract. Start by reading the capability projection, then create or select the workspace and project. Do not assume an unavailable capability from a successful login.

GET /api/capabilities

Read the capabilities available to this installation.

GET /api/session

Read the authenticated session and transport.

GET /api/workspaces

List workspaces visible to the current principal.

GET /api/projects

List projects in the authenticated scope.

GET /api/projects/{id}/access-options

Read all access choices, the current selection, and its history.

POST /api/projects/{id}/access-selection

Select one complete, available access configuration. Human owner or maintainer authority is required.

GET /api/projects/{id}/mission-control

Read project status, custody, readiness, and governed next actions.

GET /api/runs/{id}

Read the current governed run projection.

GET /api/runs/{id}/events

Read append-only run activity.

GitHub Actions: what you do and what i2x does

  1. You commit the downloaded i2x workflow. It has read-only repository access and permission to request a GitHub identity token. It contains no i2x secret and no project-specific identifier.
  2. You accept the checks in i2x. A human owner or maintainer reviews the verification plan. That fixes the source digest and the exact checks the job may run.
  3. You create the CI connection. Bind the repository ID, workflow path and commit, source commit, GitHub identity subject, and i2x audience. Then copy the five non-secret values shown by the workflow manifest into GitHub repository variables.
  4. GitHub proves which job is running. The workflow presents GitHub's short-lived OIDC token. i2x verifies its signature, repository, workflow file and commit, source commit, subject, and audience before issuing a one-use five-minute evidence session.
  5. The runner executes only the accepted checks. The downloaded client verifies its own SHA-256 digest, recomputes the project digest, starts each approved executable without a command shell, and submits the complete result set.
  6. You inspect the receipt. It names the exact source, every pass or failure, provenance, limitations, and next required approval. A CI result is labelled customer CI reported, not independent verification.
POST /api/projects/{id}/ci-github-configurations

Create the human-approved binding to the current accepted plan and exact GitHub source identity.

GET .../workflow

Download the stable workflow file. Commit this file before binding its exact workflow commit.

GET .../workflow-manifest

Read the client digest and exact non-secret GitHub repository variables to configure.

POST /ci/github/exchange

Exchange GitHub's signed OIDC identity for a one-use, five-minute evidence session.

POST /ci/github/evidence

Submit the exact accepted check set from the bound source revision.

GET /api/projects/{id}/ci-github-configurations

Review which repository, workflow, source, and accepted plan are currently bound.

Nothing silently broadens access. Changing the accepted plan, workflow commit, or source commit requires a new exact binding. The workflow cannot write the repository, approve its own result, publish a release, or start recovery.

GitLab CI: what you do and what i2x does

  1. You add the downloaded i2x job. Include or merge the stable YAML into the committed top-level .gitlab-ci.yml. The job needs no personal access token, i2x secret, model credential, or repository write permission.
  2. You accept the checks in i2x. A human owner or maintainer reviews the exact source digest and checks the pipeline may execute.
  3. You bind the exact GitLab identity. Enter the immutable project ID, project path, full ref, top-level pipeline-configuration URI and commit, source commit, GitLab subject, and i2x audience.
  4. You copy five non-secret project variables. i2x displays the origin, configuration ID, audience, client URL, and client SHA-256 digest. Add them under GitLab Settings → CI/CD → Variables.
  5. GitLab authenticates the running job. The job requests a short-lived GitLab ID token. i2x verifies its signature and the bound project, ref, pipeline, job, runner, configuration, source, subject, and audience before issuing a one-use five-minute evidence session.
  6. You read the governed receipt. The client runs only the accepted checks and returns the complete result set. The receipt shows exact source, outcomes, provenance, limitations, and next safe action. It is labelled customer CI reported, not independent verification.
GET /api/projects/{id}/ci-gitlab-workflow-template

Download the stable GitLab CI job before creating the exact binding.

POST /api/projects/{id}/ci-gitlab-configurations

Bind the current accepted plan to one exact GitLab.com project, ref, pipeline configuration, and source.

GET .../workflow-manifest

Read the exact five non-secret project variables, permitted checks, and integrity digests.

POST /ci/gitlab/exchange

Exchange the signed GitLab job identity for a one-use evidence session.

POST /ci/gitlab/evidence

Submit the complete accepted result set from the bound revision.

Current provider boundary: this customer setup supports GitLab.com. A different project, ref, top-level configuration, source, subject, audience, client, or accepted plan is rejected. Self-managed GitLab issuers are not accepted by this public configuration.

Browser authentication

Mutating browser requests require the secure session, same-origin request, and CSRF binding issued by i2x. Connector runtimes use their separate scoped connector protocol. Never place a connector token in browser JavaScript or a repository.

MCP operations

The connector exposes only the operations allowed for its current task. Call tools/list instead of assuming every operation is available.

connector.prove

Complete the one-time connection challenge.

task.list

List assigned work without claiming it.

task.claim

Claim one task and receive its permitted tools, prohibitions, inputs, and required outputs.

task.complete

Return a structured agent report. This does not verify the result.

project.inspect

Record a project inventory with its stated provenance.

plan.propose

Propose observable behavior to protect, for human review.

verification.request

Propose executable checks; it does not run or pass them.

rehearsal.request

Propose a source-bound baseline/candidate rehearsal.

run.status

Read run state, holds, receipt metadata, and activity.

evidence.read

Read scoped evidence metadata and provenance.

finding.submit

Submit an evidence-linked QA finding for review.

repair.propose

Submit a reproduced repair candidate; it does not claim success.

release.prepare

Prepare an exact release request for separate approval.

recovery.prepare

Prepare an exact recovery request for separate approval.

Any CI system: customer-signed job identity

Use this path for Jenkins, Buildkite, TeamCity, Azure Pipelines, Bitbucket Pipelines, self-hosted automation, or another CI system that can run Node.js and protect a secret variable.

  1. Generate one Ed25519 key pair. Register only its public JWK with i2x. Keep the private JWK in the CI secret store; i2x never receives it.
  2. Bind the expected scope. An owner or maintainer accepts the checks and records the signer, audience, project, full ref, pipeline definition, and source revision.
  3. Run the generic client. It creates a unique four-minute assertion and signs it locally.
  4. i2x verifies before returning checks. The signature, key, project, ref, pipeline, source, job, runner, nonce, and time window must match. Replays are rejected.
  5. The client runs only accepted checks. It uses no command shell, bounds time and output, and rejects source drift.
  6. Read the honest receipt. It is labelled customer CI signed and customer-configured signing key, not provider-attested or independently verified.
POST /api/projects/{id}/ci-generic-configurations

Register the public key and exact expected job scope.

GET /downloads/i2x-generic-ci-client.mjs

Download the provider-neutral Node.js client and pin its SHA-256 digest.

POST /ci/generic/exchange

Exchange the locally signed assertion for a one-use evidence session.

POST /ci/generic/evidence

Return the complete accepted result set.

Trust boundary: this proves possession of the customer-configured private key and exact job scope. It does not prove provider attestation. Prefer a supported provider OIDC integration when available.

Understand every returned result

Agent report

A schema-checked result from the assigned agent. Useful, but not independent verification.

Evidence receipt

A source- and environment-bound record of expected and observed values, checks, exclusions, and provenance.

Current assurance

Passing evidence for the exact current revision from an accepted verification path. Changed source, expiry, or revoked trust removes the claim.

Public security boundary

  • Connections are workspace-scoped and revocable.
  • Provider credentials remain with the customer when using the official Codex or Claude client.
  • An agent cannot approve its own proposal or upgrade its own report into independent evidence.
  • Release and recovery require exact scope, current supporting evidence, and separate human approval.
  • Use the least repository, network, and write permission needed for the selected configuration.