> ## Documentation Index
> Fetch the complete documentation index at: https://checkfu.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Codex end to end

> Build the pinned Vercel Codex adapter image, adopt and verify it, then drive a settled Session through the public API.

<Warning>
  The Agent creation and Session-launch portion of this guide is migration-fenced:
  it still shows the retired Draft/Release API. Use [Agents](/concepts/agents)
  for current Agent creation; CMA-compatible Session launch is not yet available.
</Warning>

This guide walks the `codex` catalog entry from nothing to a settled
Session: build the pinned generic Vercel image, adopt it as a HarnessProfile, pass
conformance for your exact tuple, publish an Agent, and read the settled
event log. Every step uses the public surface — the same
`POST /v1/harness-profiles` + verification path any custom image takes.
Concept truth lives in
[Harnesses and models](/concepts/harnesses-and-models#codex-through-its-app-server);
this page is the journey.

## Where this harness stands

* The catalog entry is `image_required`: Checkfu publishes no ready default,
  so you build the exact Codex recipe in the generic Vercel workload and
  adopt its digest.
* Vercel's maintained HarnessAgent adapter owns the pinned Codex app-server
  mapping. Checkfu owns the generic ACP boundary, sandbox, policy, and log.
* The adapter implements native mid-turn steering and cooperative interrupt,
  but the catalog ceiling keeps the stock ACP degradations until
  exact-adapter signed conformance evidence exists; declarations alone
  never raise an advertised ceiling.
* Checkfu has not yet recorded a default-tuple ConformanceReport for this
  entry, so it does not yet clear the full
  [support ladder](/concepts/harnesses-and-models#capability-evidence-and-conformance).
  The verification below produces that evidence for *your* tuple; until one
  passes, ordinary Runs on the profile are refused by design.

<Warning>
  The Checkfu CLI has no self-service public installation channel during
  private alpha. CLI examples below assume access through an explicitly
  authorized alpha arrangement; see
  [CLI access in private alpha](/getting-started/cli-access) for the
  source-checkout and HTTP alternatives.
</Warning>

<Steps>
  <Step title="Build the pinned Vercel image" titleSize="h2">
    The generic builder derives the exact Codex adapter and runtime closure
    from the reviewed Vercel cohort and validates every lock version and
    integrity before producing the unprivileged final image.

    ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
    pnpm vercel-harness-image:build --harness codex
    ```

    The command builds the image, publishes it through an owned local
    registry so the result is content-addressed, verifies it against the
    published image contract, and prints the immutable `name@sha256:...`
    reference. Keep it:

    ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
    export CODEX_IMAGE="<the printed name@sha256:... reference>"
    ```
  </Step>

  <Step title="Adopt the image as a HarnessProfile" titleSize="h2">
    <CodeGroup>
      ```sh CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
      pnpm exec checkfu harness add codex \
        --name codex \
        --image "$CODEX_IMAGE"
      ```

      ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
      curl --request POST https://api.checkfu.com/v1/harness-profiles \
        --header "Authorization: Bearer $CHECKFU_API_KEY" \
        --header "Checkfu-Version: 2026-08-27" \
        --header "Idempotency-Key: adopt-codex-$(uuidgen)" \
        --header "Content-Type: application/json" \
        --data '{
          "name": "codex",
          "source": {
            "kind": "recipe",
            "name": "codex",
            "image": "'"$CODEX_IMAGE"'"
          }
        }'
      ```
    </CodeGroup>

    The response is the profile with `version: 1` and the pinned
    `driver_version: "checkfu:acp-v1@1"`. The profile admits nothing yet —
    custom OCI profiles are fail-closed until their exact runtime tuple
    passes conformance.
  </Step>

  <Step title="Verify conformance for your exact tuple" titleSize="h2">
    Select the SandboxProfile and ModelRoutingProfile the Agent will actually use.
    One constraint is specific to this harness: the adapter writes
    `wire_api = "responses"` into the Codex configuration it generates, so
    the model routing profile must route an OpenAI-responses-dialect model — an
    Anthropic-only profile is unreachable for it, and admission says so
    instead of letting the turn fail at the model gateway.

    <CodeGroup>
      ```sh CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
      pnpm exec checkfu harness verify codex \
        --sandbox standard \
        --model primary \
        --wait
      pnpm exec checkfu harness status codex
      ```

      ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
      curl --request POST \
        "https://api.checkfu.com/v1/harness-profiles/$CHECKFU_HARNESS_PROFILE_ID/verifications" \
        --header "Authorization: Bearer $CHECKFU_API_KEY" \
        --header "Checkfu-Version: 2026-08-27" \
        --header "Idempotency-Key: verify-codex-$(uuidgen)" \
        --header "Content-Type: application/json" \
        --data '{
          "expected_version": 1,
          "environment": "standard",
          "model_routing_profile_key": "primary"
        }'
      ```
    </CodeGroup>

    Verification queues a conformance Run that an enrolled Runner claims and
    executes against the real image. The passing ConformanceReport is pinned
    to the image digest, profile version, driver, sandbox, model routing profile,
    policy, and suite revision; changing any of them — or reaching the
    report's 30-day expiry — requires fresh evidence. On a durable sandbox
    the report records disk checkpointing with Codex thread resume: the
    adapter persists rollouts and thread markers, so a continued Session
    resumes from the sandbox filesystem instead of rebuilding blind.
  </Step>

  <Step title="Create and publish an Agent" titleSize="h2">
    With a passing report, the profile is an ordinary harness name an Agent
    can reference:

    ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl --request POST https://api.checkfu.com/v1/agents \
      --header "Authorization: Bearer $CHECKFU_API_KEY" \
      --header "Checkfu-Version: 2026-08-27" \
      --header "Idempotency-Key: create-agent-$(uuidgen)" \
      --header "Content-Type: application/json" \
      --data '{
        "name": "refactoring-agent",
        "instructions": "Refactor the mounted project and explain every change.",
        "harness": "codex",
        "model_routing_profile_key": "primary",
        "environment": "standard"
      }'
    ```

    Publish version 1 with `POST /v1/agents/{id}/releases` and grant the
    Agent `use_harness`, `use_model`, and `use_environment` on the three
    governed resources, plus `invoke` for your Principal — the exact
    sequence [Create and publish an Agent](/guides/create-and-publish-an-agent)
    walks. Session admission intentionally fails closed while any one PermissionAssignment
    is absent.
  </Step>

  <Step title="Run a Session and read the settled log" titleSize="h2">
    <CodeGroup>
      ```sh CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
      pnpm exec checkfu session chat \
        --agent "$CHECKFU_AGENT_ID" \
        --principal "$CHECKFU_PRINCIPAL_ID" \
        "Summarize what this harness can and cannot do."
      ```

      ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
      curl "https://api.checkfu.com/v1/sessions/$CHECKFU_SESSION_ID/events?limit=100" \
        --header "Authorization: Bearer $CHECKFU_API_KEY" \
        --header "Checkfu-Version: 2026-08-27" \
      ```
    </CodeGroup>

    Settlement is read from the durable event log, never inferred from
    response timing. A successful first turn ends with `run.completed`
    followed by `session.status_idle`, with the `agent.message` content and
    the model-routing, usage, and sandbox-cleanup evidence recorded between
    `run.created` and settlement. The [event catalog](/reference/events)
    names every type you will see.
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Harnesses and models" icon="cpu" href="/concepts/harnesses-and-models">
    The adoption-path model, capability ceilings, and conformance evidence rules.
  </Card>

  <Card title="Checkpoints" icon="floppy-disk" href="/concepts/checkpoints">
    How disk checkpoints and thread resume carry a Session across idle time.
  </Card>
</CardGroup>