Bring a custom harness

​

Start from a scaffold

checkfu harness init acp --directory ./my-harness

​

The wire: JSON-RPC over stdio

const input = new PassThrough()
process.stdin.pipe(input, { end: false })
process.stdin.on("end", () => {
	void (async () => {
		await new Promise((resolve) => setImmediate(resolve))
		while (activeTurn !== null) await activeTurn.done
		input.end()
	})()
})

​

initialize: declare only what you serve

const app = agent({ name: "checkfu-custom-acp" })
	.onRequest(methods.agent.initialize, () => ({
		protocolVersion: PROTOCOL_VERSION,
		agentCapabilities: { loadSession: false },
		authMethods: [],
		agentInfo: { name: "checkfu-custom-acp", version: "1" },
	}))

​

Session and turn lifecycle

	.onRequest(methods.agent.session.new, (context) => {
		if (sessionCreated)
			throw new RequestError(-32001, "this container admits exactly one ACP session")
		if (
			context.params.mcpServers.length > 0 ||
			(context.params.additionalDirectories?.length ?? 0) > 0
		) {
			throw new RequestError(-32602, "the starter does not admit local MCP servers or directories")
		}
		sessionCreated = true
		return { sessionId }
	})

			await context.client.notify(methods.client.session.update, {
				sessionId,
				update: {
					sessionUpdate: "agent_message_chunk",
					messageId: `message-${context.requestId}`,
					content: { type: "text", text },
				},
			})
			if (turn.cancelled) return { stopReason: "cancelled" }
			return { stopReason: "end_turn" }

​

Qualify the complete agent journey

• Complete useful work with a real native tool or granted MCP tool, and inspect the recorded tool result as well as the final response.
• Start a subsequent Run in the same Session and check the context your agent actually retains. A successful first turn does not prove continuation. The scaffold above declares loadSession: false; connect and qualify your own state handling before advertising restoration.
• Cancel while work is in flight. A cooperative ACP implementation handles session/cancel, stops its pending work, and settles the prompt. Check both the terminal outcome and any tool side effects. A cancellation acknowledgement does not prove that effects were undone or an upstream provider request terminated; a notification alone does not prove that execution stopped.
• Exercise a known provider refusal, then submit a valid fresh prompt through your release’s supported retry path. Check the failed Run’s recorded outcome, the next Run’s useful result, and the absence of credentials in errors or diagnostics. Pinned BYOK refusal must not switch to paid managed tokens. A successful retry does not establish native checkpoint restoration or reverse effects from the failed attempt. If a request, tool effect, cancellation, or custody callback has an uncertain outcome, retain its original operation and use only the release’s supported reconciliation path. Do not create a new operation or reopen the native owner to repeat an effect whose outcome is unknown; a joined or closed local process does not establish rollback.
• Exercise recovery only for the mechanisms your release supports. An externally custodied native checkpoint must be exported and imported through the declared Checkfu extensions. Native restore requires nonempty, bounded native state. The wire value same_run_resume also covers completed conversation state carried into a later Run of the same frozen Session; its name does not require the same Checkfu Run ID. Pending approvals require their exact admitted continuation, rather than an unrelated new input. Keep that state outside agent-readable files, and do not put provider credentials in it.

​

The governed model plane arrives in the environment

	const response = await fetch(`${baseUrl.replace(/\/$/u, "")}/responses`, {
		method: "POST",
		headers: {
			accept: "application/json",
			authorization: `Bearer ${token}`,
			"content-type": "application/json",
		},
		body: JSON.stringify({ model: "checkfu-admitted-model", input }),
		signal,
	})
	if (!response.ok) {
		await response.body?.cancel()
		throw new Error(`model plane returned HTTP ${response.status}`)
	}

​

The platform tool plane: MCP handoff

​

The image contract

​

Register, verify, run

checkfu harness test oci \
  --name my-harness \
  --image ghcr.io/acme/my-harness@sha256:<64-hex-digest> \
  --entrypoint /usr/local/bin/node \
  --arg /opt/checkfu/custom-acp.mjs \
  --protocol acp-v1 \
  --working-directory /workspace

checkfu harness add oci \
  --name my-harness \
  --image ghcr.io/acme/my-harness@sha256:<64-hex-digest> \
  --entrypoint /usr/local/bin/node \
  --arg /opt/checkfu/custom-acp.mjs \
  --working-directory /workspace \
  --model-wire openai_responses \
  --mcp-delivery none \
  --platform linux/amd64

checkfu harness verify my-harness --sandbox standard --model primary --wait

​

Upgrade and roll back one logical harness

checkfu harness update my-harness oci \
  --image ghcr.io/acme/my-harness@sha256:<new-64-hex-digest> \
  --working-directory /workspace \
  --platform linux/amd64 \
  --expected-version 1 \
  --verify \
  --sandbox standard \
  --model primary

checkfu harness update my-harness release \
  --release hrel_<previous-release-id> \
  --driver checkfu:acp-v1@1 \
  --expected-version 2 \
  --verify \
  --sandbox standard \
  --model primary

​

Or hand us the repository instead

1. harness-recipe.json at the repository root — the recipe-in-repo path. Commit the recipe plus the context its install command needs. Checkfu prepares a Vercel-shaped adapter image from that recipe. You do not need a Dockerfile for this path. The selected Runner must have a recipe base configured by its operator. Adopt the result as acp-v1 with entrypoint /opt/checkfu/bin/checkfu-vercel-harness and model_wire_dialects from the recipe’s route. The private andyrewlee/checkfu-customer-harness-fixture repository is an additional example for developers who already have access. The recipe below works with your own published ACP package.
2. A Dockerfile and no recipe file — Checkfu builds that Dockerfile as a stranger image. Direct-OCI registration (checkfu harness add oci) remains the path for images you already built yourself.

{
  "schema_version": 1,
  "harness_id": "my-domain-agent",
  "source": {
    "type": "npm-simple",
    "package_name": "@acme/my-domain-agent",
    "package_version": "1.0.0"
  },
  "executable": "my-domain-agent",
  "args": [],
  "env": {},
  "forward_env": [],
  "model_route": "openai_chat",
  "provider_env": {
    "OPENAI_BASE_URL": { "source": "gateway-base-url", "ensure_suffix": "/v1" },
    "OPENAI_API_KEY": { "source": "gateway-api-key" }
  },
  "builtin_tools": []
}

{
  "builtin_tool_filtering_mapping": {
    "type": "session-meta",
    "key": "company.allowed_tools"
  }
}

{
  "native_model": "my-deepseek-model",
  "model_catalog": [
    { "id": "my-deepseek-model", "context_window": 98304, "max_tokens": 12345 }
  ]
}

# In your own checkout, after pushing the commit that contains harness-recipe.json.
COMMIT_SHA="$(git rev-parse HEAD)"

checkfu harness build github \
  --repository https://github.com/acme/my-harness \
  --ref "$COMMIT_SHA" \
  --runner-pool "$CHECKFU_RUNNER_POOL_ID" \
  --recipe \
  --mcp-delivery session_http \
  --platform linux/amd64 \
  --profile-name my-harness \
  --adopt \
  --verify \
  --sandbox standard \
  --model primary

checkfu harness build status hbld_<build-id>

​

Prepare an Environment from the release

checkfu agent plan ./customer-agent
checkfu agent apply ./customer-agent --idempotency-key customer-invoice-agent-1 --json

checkfu harness verify my-harness \
  --sandbox customer-invoice-prepared --model primary --wait

​

Check execution readiness

checkfu doctor --agent AGENT_ID --environment ENVIRONMENT_ID

​

Where to go next

• To understand the boundary, use the maintained CLI ACP template — the protocol floor is intentionally minimal, and its omitted capabilities are explicit.
• To adapt an SDK-authored agent, use the OpenAI Agents SDK over ACP example — it pins the official SDK, routes its fixed model through Checkfu’s gateway, disables the SDK’s separate trace exporter, and declares no MCP handoff.
• For the contract itself, Harness wire extensions and the schema and vector artifacts remain the normative source.