Let XCB own provider sign-in and process custody while your application owns its data and actions. The application interface accepts a bounded prompt and returns untrusted text. It runs with no tools, hooks, session history, continuation, or account fallback.
Discover qualified routes
xcb --json generate --capabilitiesThis reads local metadata without provider refresh or inference. Select only an account with available: true and one of its exact model keys. supported: true alone does not mean an account is available.
Capabilities verifies local executable bytes and can take several seconds. Give discovery a bounded timeout separate from the generation deadline; 90 seconds is a practical desktop integration recommendation, not a protocol timing guarantee.
When launching XCB from an app, preserve HOME or set XCB_STATE in the child environment, even when passing --state; the current CLI still resolves its default root. Close unused stdin for discovery and drain stdout and stderr while waiting for the subprocess to finish.
supported: false until the exact XCB executable, provider, account, and model have current evidence. A successful sign-in or doctor check is not enough. Do not substitute xcb run when generation is unavailable.Generate one response
Start the admitted executable directly with --json generate. Write one UTF-8 JSON document to stdin, close stdin, and drain stdout and stderr while waiting for the result. Keep both streams bounded. Replace both account and model placeholders with the exact values from capabilities.
{
"version": 1,
"account": "<available-account-id>",
"model": "<qualified-full-model-key>",
"prompt": "Summarize the supplied text in one sentence.",
"timeoutMs": 60000,
"maxOutputBytes": 65536
}All six fields are required; additional fields are rejected. The total input is limited to 1 MiB. The timeout range is 1,000–120,000 milliseconds and the output limit is 1–262,144 bytes. Prompts must be nonempty and contain no NUL.
A successful response has status: completed, generated text, and an outcome proving the provider has joined with no application effects. A nonzero exit returns a closed failure object without generated text. Validate the text against your own application schema before acting on it.
Keep application actions in your host
XCB performs inference, not your application’s file access, network requests, or message delivery. Your host controls recipient selection, authorization, output validation, and durable request records. TextButler is a reference consumer that keeps contact access and messaging approvals in its own host.
Send SIGINT or SIGTERM to request cancellation, then wait for cleanup. The inference deadline does not prove that the provider has stopped. An uncertain result keeps account custody and must not be blindly retried.
Qualification and renewal
Qualification uses actual host boundary evidence and a separate fixed live challenge. Receipts expire no later than 24 hours after evidence collection begins. Runtime, provider, or explicit credential changes can invalidate them earlier. Reading capabilities never extends their lifetime.
Use the host qualification procedure before accepting application traffic. The explicit macOS Claude renewal helper binds one previously qualified deployment and account; it is not activated by installing XCB.
For the complete discovery and response schemas, error codes, expiry rules, and custody contract, read the application API reference.