How a governed request moves
What runs where
| How you start | Where Codex or Claude runs | What i2x receives | What you get back |
|---|---|---|---|
| Local folder | On 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 CI | In 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 automation | In 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/capabilitiesRead the capabilities available to this installation.
GET /api/sessionRead the authenticated session and transport.
GET /api/workspacesList workspaces visible to the current principal.
GET /api/projectsList projects in the authenticated scope.
GET /api/projects/{id}/access-optionsRead all access choices, the current selection, and its history.
POST /api/projects/{id}/access-selectionSelect one complete, available access configuration. Human owner or maintainer authority is required.
GET /api/projects/{id}/mission-controlRead project status, custody, readiness, and governed next actions.
GET /api/runs/{id}Read the current governed run projection.
GET /api/runs/{id}/eventsRead append-only run activity.
GitHub Actions: what you do and what i2x does
- 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.
- 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.
- 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.
- 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.
- 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.
- 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-configurationsCreate the human-approved binding to the current accepted plan and exact GitHub source identity.
GET .../workflowDownload the stable workflow file. Commit this file before binding its exact workflow commit.
GET .../workflow-manifestRead the client digest and exact non-secret GitHub repository variables to configure.
POST /ci/github/exchangeExchange GitHub's signed OIDC identity for a one-use, five-minute evidence session.
POST /ci/github/evidenceSubmit the exact accepted check set from the bound source revision.
GET /api/projects/{id}/ci-github-configurationsReview 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
- 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. - You accept the checks in i2x. A human owner or maintainer reviews the exact source digest and checks the pipeline may execute.
- 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.
- 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.
- 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.
- 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-templateDownload the stable GitLab CI job before creating the exact binding.
POST /api/projects/{id}/ci-gitlab-configurationsBind the current accepted plan to one exact GitLab.com project, ref, pipeline configuration, and source.
GET .../workflow-manifestRead the exact five non-secret project variables, permitted checks, and integrity digests.
POST /ci/gitlab/exchangeExchange the signed GitLab job identity for a one-use evidence session.
POST /ci/gitlab/evidenceSubmit 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.proveComplete the one-time connection challenge.
task.listList assigned work without claiming it.
task.claimClaim one task and receive its permitted tools, prohibitions, inputs, and required outputs.
task.completeReturn a structured agent report. This does not verify the result.
project.inspectRecord a project inventory with its stated provenance.
plan.proposePropose observable behavior to protect, for human review.
verification.requestPropose executable checks; it does not run or pass them.
rehearsal.requestPropose a source-bound baseline/candidate rehearsal.
run.statusRead run state, holds, receipt metadata, and activity.
evidence.readRead scoped evidence metadata and provenance.
finding.submitSubmit an evidence-linked QA finding for review.
repair.proposeSubmit a reproduced repair candidate; it does not claim success.
release.preparePrepare an exact release request for separate approval.
recovery.preparePrepare 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.
- 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.
- Bind the expected scope. An owner or maintainer accepts the checks and records the signer, audience, project, full ref, pipeline definition, and source revision.
- Run the generic client. It creates a unique four-minute assertion and signs it locally.
- i2x verifies before returning checks. The signature, key, project, ref, pipeline, source, job, runner, nonce, and time window must match. Replays are rejected.
- The client runs only accepted checks. It uses no command shell, bounds time and output, and rejects source drift.
- 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-configurationsRegister the public key and exact expected job scope.
GET /downloads/i2x-generic-ci-client.mjsDownload the provider-neutral Node.js client and pin its SHA-256 digest.
POST /ci/generic/exchangeExchange the locally signed assertion for a one-use evidence session.
POST /ci/generic/evidenceReturn 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.