Choose a harness
Checkfu’s managed roster covers eight families:
Checkfu owns their integration and support. Choose the release that supports
your model route and the capabilities your application needs. Membership in
this roster does not make every model or feature available on every release.
Bring your own harness
Build a harness for your domain or adapt an existing implementation, including a derivative of Pi or Codex. Official and custom implementations use the same adapter contract and release qualification. You own support for your custom implementation. Start from the interface your harness exposes. Its ancestry or package name does not determine its capabilities.
Pi Durable on Cloudflare and Pi coding-agent native extensions are separate
integrations. Neither one’s capabilities establish the other’s. The same rule
applies to a native SDK package and an ACP image.
The custom harness guide covers the public ACP
and one-shot image authoring paths. It is not a scaffold for every interface in
the table. Internal native SDK exports do not establish a public BYOH API.
For invited CLI users, get CLI access, then start
an ACP implementation with:
oneshot for the one-shot scaffold. Package and qualify the exact release
before using it; the scaffold alone does not prove your implementation’s
capabilities.
Choose a model
A model must be compatible with both the selected harness release and its model route. Matching a provider name is not enough. Check the request format, model metadata, and features your application uses.
Use the harness/model matrix
for request-format compatibility and the
capability declarations
for release details. A shared format does not guarantee every model feature.
Unsupported combinations are refused; Checkfu does not silently substitute a
provider, model, format, or paid supply.
Model access
An Agent’s model is reached one of two ways:- Managed by Checkfu. Name a model Checkfu supplies, such as
google/gemini-3.6-flashon Checkfu’s OpenRouter account. Usage is billed to your plan as platform supply. No key is needed. - Your own key. Add a model credential, then pin it from the Agent’s model config. Usage is billed by the provider to your account; Checkfu’s model charge is zero.
A custom endpoint uses a public DNS hostname over HTTPS on port 443 and speaks
one of the three formats, such as a hosted LiteLLM, vLLM, or Ollama deployment.
Set
base_url to its API root, without URL credentials, a query or a fragment.
Endpoints on a private network are not reachable.
model object. The public
POST /v1/agents request accepts a model ID, provider, and credential pin;
model_routing_profile_key and environment_key are not fields of this request.
For example, with a compatible cline harness:
Session configuration
The Agent records your harness, model, instructions, and tools in an immutable AgentVersion. Select the Environment separately when starting a Session. Checkfu freezes the selected configuration for that Session; later edits apply to future Sessions. Your harness’s native state and logs do not replace the Session’s accepted history. See Product model for Agent, Session, and Run boundaries. Checkfu-managed and customer-operated Cloudflare use the same product model; deployment ownership is separate from harness choice, model access, and ConnectedRuntime attachment.Selection refusals
model.no_eligible_model is not the error for every invalid selection. A pinned
BYOK credential may name a provider-served model outside the reviewed catalog;
saving it does not prove the provider serves that model or that the harness can
use it. Inspect the actual provider and model in Run and Usage records.
For a custom HarnessProfile, the dashboard distinguishes incompatible formats,
unverified compatibility when the release declares no formats, and unavailable
information when the release cannot be read. These notices do not prevent
creating an Agent. Creation saves configuration; compatibility is checked when
a Session starts. An omitted format declaration is unconstrained at admission,
not proof of compatibility.
The dashboard pins a custom profile as name@N, its current published Version.
The API also accepts name@latest or a bare profile name to select the profile
head. A catalog harness uses its bare name. The Agent’s harness selection stays
immutable; a Session freezes the release it selected.
In the dashboard, Model credentials → Add credential creates the credential;
Create Agent → Bring your own key selects and pins it. Credential creation
is a human step. CLI and MCP hand it off to the dashboard so a secret need not
pass through an agent. The SDK and checkfu agent create --input accept the
public model configuration above. See SDK access
and CLI access for artifact distribution.
Native execution
Native Cloudflare Agents execution selects an exact model from the pinned native catalog, or an explicitly declared custom model with the metadata below. It preserves the model’s request format, which must match the Session’s frozen credential route. Naming a custom HTTPS endpoint or saving a noncatalog model alone does not supply that metadata or transport. The gateway’s provider table is not a native execution guarantee. The exact package release, adapter, model route, and deployment must support the selected combination. Native package tests do not qualify an image, and an image’s conformance report does not qualify a native Durable Object harness.Custom model declarations for native execution
A native model outside the reviewed SDK catalog needs explicit protocol metadata on its model candidate. Declarecontext_window_tokens, native_capabilities,
and native_sdk_estimation; naming a catalog model as an alias does not supply
missing custom metadata. Pin a credential with an explicit base_url and
api_format, even when its provider has a default endpoint or supports several
formats. Missing endpoint or format metadata is refused on this custom native
path; Checkfu does not infer it from the model name.
native_capabilities.version is 1. Select openai_chat, openai_responses,
or anthropic_messages as wire_format, matching the pinned credential. Declare
an output-token limit no greater than the context window, unique supported
text/image input modalities, reasoning support, all seven thinking-level
mappings, and the compatibility flags for that format. A null thinking mapping
means no value is sent for that level. These declarations describe serialization;
they do not grant tools, egress, model access, or provider capabilities.
native_sdk_estimation uses version: 1,
unit: "usd_per_million_tokens", and source: "profile_declared". All four
finite, nonnegative rates are required: input, output, cache_read, and
cache_write. An explicit zero is an SDK display estimate, not a free-provider
claim. Managed quotes, Usage, Budgets, and charges use their own authoritative
accounting; omitted rates never become zero.
Session admission retains the original credential generation, endpoint, request
format, and resource version. Native requests must match that original endpoint
and current authority before dispatch. Later credential edits do not rewrite
those coordinates. Missing metadata, incompatible formats, or endpoints the
selected serializer cannot represent are refused; they never switch to a
catalog alias or paid managed supply.
This declaration does not make a native harness launchable. The selected release
still needs its own qualified execution prerequisites and supported capabilities.
Consult capability status for the actual offering.
Native image configuration
Some images accept non-secret configuration validated against the schema stored with their release. For example, an image may acceptnative_model and a
model_catalog with id, context_window, and max_tokens. These are
caller-declared values, not provider-verified capacity or support claims.
Where that schema applies, the selected model must occur exactly once and
max_tokens must be less than context_window. A model-only selection uses the
image’s catalog metadata and defaults where permitted. Empty configuration is
valid only for an image that supports it; locked native profiles reject these
overrides.
Image configuration does not select the model credential route or override the
model for an active turn. Follow the image’s native hot-reload rules. A schema
change requires a compatible image and new release; ordinary configuration
changes follow profile versioning. Qualify the image, configuration, and model
route together.
Support
Support belongs to an exact release and configuration. A package, catalog row, image build, or deterministic fixture does not establish a customer offering. The roster governs managed families; custom implementations and supported ConnectedRuntimes follow their own contracts. Research entries outside the managed roster are not additional supported families. Local fixtures remain for development and tests. For custom images, server-issued, signature-verified conformance evidence is required. An immutable recipe image or release, an authorized HarnessProfile, its Environment, anduse_harness permission remain separate requirements.
Catalog profile creation needs a published default image; otherwise it returns
409 validation.conflict.
Changing the binary, image digest, adapter, protocol, Environment, model route,
or policy can require new qualification. Distribution and license terms,
hosting, and authentication also apply to the exact combination. One supported
route does not qualify every route in the family.
Portability
Agent, Environment, Session, and event semantics stay consistent across harnesses. Their native capabilities and private state can differ. Switching a harness does not promise it can resume another harness’s process state or safely retry an uncertain external effect. Preserve the original Session configuration, permission, Usage, and effect records during recovery.Next steps
- Quickstart: select an Agent and Environment and start a Session.
- Run Claude Agent or Run Codex: configure a managed family.
- Bring a custom harness: implement and qualify the ACP or one-shot image contract.
- Harness extensions: inspect protocol, model-format, and capability details.