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.

The Agent creation and Session-launch portion of this guide is migration-fenced: it still shows the retired Draft/Release API. Use Agents for current Agent creation; CMA-compatible Session launch is not yet available.

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; 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. The verification below produces that evidence for your tuple; until one passes, ordinary Runs on the profile are refused by design.

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 for the source-checkout and HTTP alternatives.

1. Build the pinned Vercel image

   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.

   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:

   export CODEX_IMAGE="<the printed name@sha256:... reference>"
   
2. Adopt the image as a HarnessProfile

   CLI

   pnpm exec checkfu harness add codex \
     --name codex \
     --image "$CODEX_IMAGE"
   

   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.

3. Verify conformance for your exact tuple

   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.

   CLI

   pnpm exec checkfu harness verify codex \
     --sandbox standard \
     --model primary \
     --wait
   pnpm exec checkfu harness status codex
   

   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.

4. Create and publish an Agent

   With a passing report, the profile is an ordinary harness name an Agent can reference:

   cURL

   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 walks. Session admission intentionally fails closed while any one PermissionAssignment is absent.

5. Run a Session and read the settled log

   CLI

   pnpm exec checkfu session chat \
     --agent "$CHECKFU_AGENT_ID" \
     --principal "$CHECKFU_PRINCIPAL_ID" \
     "Summarize what this harness can and cannot do."
   

   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 names every type you will see.

Next steps

Harnesses and models

The adoption-path model, capability ceilings, and conformance evidence rules.

Checkpoints

How disk checkpoints and thread resume carry a Session across idle time.