Run Claude Agent end to end

Build the pinned Vercel Claude Agent 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 claude-code 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

Be clear about what you are adopting before you start:

• The catalog entry is image_required: Checkfu publishes no ready default, so you build the exact Claude Agent recipe in the generic Vercel workload and adopt its digest.
• Vercel’s maintained HarnessAgent adapter owns the Claude SDK mapping. Checkfu owns the generic ACP boundary, sandbox, policy, and durable log.
• Distribution of a hosted default image remains gated on Anthropic terms approval, so building and qualifying the image is a private act inside your own Workspace.
• Checkfu has not yet recorded a default-tuple ConformanceReport for this entry, so it does not yet clear the full support ladder. The verification you run 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 Claude Agent adapter, SDK, 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 claude-code
   

   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 CLAUDE_CODE_IMAGE="<the printed name@sha256:... reference>"
   

   Only a digest-pinned reference is accepted downstream; tags are rejected before anything persists.

2. Adopt the image as a HarnessProfile

   Adoption goes through the catalog entry’s recipe source: you name the entry and supply the image you built. The release inherits the published image contract (entrypoint, non-root user, read-only root, working directory), so there is nothing else to declare.

   CLI

   pnpm exec checkfu harness add claude-code \
     --name claude-code \
     --image "$CLAUDE_CODE_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 speaks only Anthropic’s /v1/messages wire dialect, so the model routing profile must route an Anthropic-dialect model — an OpenAI-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 claude-code \
     --sandbox standard \
     --model primary \
     --wait
   pnpm exec checkfu harness status claude-code
   

   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. The report also records the qualified semantics for the tuple: structured events, observed subagents, disk checkpoints, and the honest degradations for everything the signed suite has not actively exercised.

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-24" \
     --header "Idempotency-Key: create-agent-$(uuidgen)" \
     --header "Content-Type: application/json" \
     --data '{
       "name": "code-reviewer",
       "instructions": "Review the mounted project and report defects with evidence.",
       "harness": "claude-code",
       "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.

Harness extensions

The checkfu ACP extensions and the generated capability matrix.