Skip to main content
ChappieConfiguration is the single struct that governs every major SDK behaviour: where credentials live in Keychain, which model handles requests, how the harness shapes the assistant’s persona, how aggressively the SDK retries rate-limited calls, and which streaming transport to use. Create one configuration object per user or session and pass it to both Chappie.authSession(configuration:) and Chappie.client(configuration:) so both share identical settings.

​
Configuration fields

Every field has a sensible default. Override only what your app needs.
​
keychainService
String
default:"\"com.chappie.sdk\""
The Keychain service name that groups credentials for this SDK instance. Change this to your own reverse-DNS identifier (for example, "com.myapp.chappie") so your app’s credentials are isolated from the SDK default.
​
keychainAccount
String
default:"\"default\""
The Keychain account name within the service. For multi-account apps, pass a stable per-user identifier such as a user ID here so each account gets its own isolated credential slot.
​
keychainAccessGroup
String?
default:"nil"
An optional Keychain access group in the form "TEAMID.com.example.shared". Set this only when your app has a Keychain Sharing entitlement and you want credentials accessible to an extension or a sibling app in the same group. Leave nil for single-app setups.
​
keychainAccessibility
ChappieKeychainAccessibility
default:".whenUnlockedThisDeviceOnly"
Controls when the Keychain item is readable. The default (.whenUnlockedThisDeviceOnly) is the most secure option and prevents credentials from leaving the device or being read while locked. Use .afterFirstUnlockThisDeviceOnly only if your app genuinely needs to read credentials in the background after the first unlock.
​
model
String
default:"\"gpt-5.5\""
The model slug passed to ChatGPT/Codex. Defaults to ChappieClient.defaultModel ("gpt-5.5"). You can also change the active model at runtime by calling await client.selectModel(...).
​
harness
ChappieHarness
default:".default"
The harness that shapes the assistant’s persona, declares capabilities, and registers tool descriptors in the request context. The default harness includes a guardrail that prevents the model from presenting itself as the Codex desktop app. Override this with your own ChappieHarness to declare app-specific capabilities and tools.
​
rateLimitBackoff
ChappieRateLimitBackoffPolicy
default:".default"
The retry policy for HTTP 429 responses. The default policy retries up to 2 times with a 1-second initial delay, capped at 30 seconds, and honours the Retry-After response header when present. See Rate Limit Backoff for all options.
​
streamingTransportPolicy
ChappieStreamingTransportPolicy
default:".default"
Controls whether streaming prefers WebSocket (with automatic HTTP/SSE fallback) or HTTP/SSE only. The default policy attempts WebSocket with up to 5 reconnection attempts before falling back. See Streaming Transport for details.

​
Creating a configuration

Pass a ChappieConfiguration to both factory methods so auth and client share the same Keychain slot and SDK settings. 
let config = ChappieConfiguration(
    keychainAccount: currentUser.id,
    model: "gpt-5.5",
    harness: myHarness,
    rateLimitBackoff: .default,
    streamingTransportPolicy: .default
)

let authSession = Chappie.authSession(configuration: config)
let client = Chappie.client(configuration: config)
Pass the same ChappieConfiguration to both Chappie.authSession(configuration:) and Chappie.client(configuration:). Using different configurations for the two factory methods is valid but means they will look up credentials in different Keychain slots.

​
Per-call overrides without a configuration object

For quick setups where you only need to customise model, harness, or retry behaviour — without changing Keychain settings — use the Chappie.client(model:harness:rateLimitBackoff:streamingTransportPolicy:) overload directly: 
let client = Chappie.client(
    model: "gpt-5.5",
    harness: myHarness,
    rateLimitBackoff: ChappieRateLimitBackoffPolicy(maxRetries: 3)
)
This creates a client with all Keychain fields at their defaults (service: "com.chappie.sdk", account: "default"), suitable for single-account apps that only need to tweak model or retry behaviour.

Rate Limit Backoff

Tune retry counts, delays, and Retry-After header behaviour for 429 responses.

Streaming Transport

Switch between WebSocket with SSE fallback and HTTP/SSE-only transport modes.

Keychain Storage

Configure Keychain service, account, access groups, and accessibility for credential storage.

Security Model

Understand trust boundaries, token exposure, and privacy manifest details.