> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chappiesdk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ChappieConfiguration: Chappie SDK Behaviour and Defaults

> Learn how ChappieConfiguration controls Keychain storage, model selection, harness, rate-limit backoff, and streaming transport across your entire app.

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

<ParamField path="keychainService" type="String" default="&#x22;com.chappie.sdk&#x22;">
  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.
</ParamField>

<ParamField path="keychainAccount" type="String" default="&#x22;default&#x22;">
  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.
</ParamField>

<ParamField path="keychainAccessGroup" type="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.
</ParamField>

<ParamField path="keychainAccessibility" type="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.
</ParamField>

<ParamField path="model" type="String" default="&#x22;gpt-5.5&#x22;">
  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(...)`.
</ParamField>

<ParamField path="harness" type="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.
</ParamField>

<ParamField path="rateLimitBackoff" type="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](/configuration/rate-limit-backoff) for all options.
</ParamField>

<ParamField path="streamingTransportPolicy" type="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](/configuration/streaming-transport) for details.
</ParamField>

## Creating a configuration

Pass a `ChappieConfiguration` to both factory methods so auth and client share the same Keychain slot and SDK settings.

```swift theme={null}
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)
```

<Note>
  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.
</Note>

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

```swift theme={null}
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.

## Related configuration topics

<CardGroup cols={2}>
  <Card title="Rate Limit Backoff" icon="arrow-rotate-right" href="/configuration/rate-limit-backoff">
    Tune retry counts, delays, and `Retry-After` header behaviour for `429` responses.
  </Card>

  <Card title="Streaming Transport" icon="wave-sine" href="/configuration/streaming-transport">
    Switch between WebSocket with SSE fallback and HTTP/SSE-only transport modes.
  </Card>

  <Card title="Keychain Storage" icon="key" href="/configuration/keychain">
    Configure Keychain service, account, access groups, and accessibility for credential storage.
  </Card>

  <Card title="Security Model" icon="shield" href="/security">
    Understand trust boundaries, token exposure, and privacy manifest details.
  </Card>
</CardGroup>