> ## 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 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.

<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 `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](/concepts/harnesses-and-models#claude-agent-via-the-claude-agent-sdk-shim);
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](/concepts/harnesses-and-models#capability-evidence-and-conformance).
  The verification you run 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 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.

    ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
    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:

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

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

  <Step title="Adopt the image as a HarnessProfile" titleSize="h2">
    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.

    <CodeGroup>
      ```sh CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
      pnpm exec checkfu harness add claude-code \
        --name claude-code \
        --image "$CLAUDE_CODE_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-claude-code-$(uuidgen)" \
        --header "Content-Type: application/json" \
        --data '{
          "name": "claude-code",
          "source": {
            "kind": "recipe",
            "name": "claude-code",
            "image": "'"$CLAUDE_CODE_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 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.

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

      ```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-claude-code-$(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. 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.
  </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": "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](/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="Harness extensions" icon="puzzle-piece" href="/concepts/harness-extensions">
    The checkfu ACP extensions and the generated capability matrix.
  </Card>
</CardGroup>