# CopilotKitProvider

> The React Native provider that configures the CopilotKit runtime connection and shares it with all hooks and components.

## Overview [#overview]

`CopilotKitProvider` is the React Native provider for CopilotKit. Wrap your app (or the sub-tree that needs a copilot) with it to configure the runtime connection. Every hook and component below it, for example [`useCopilotKit`](/reference/react-native/hooks/useCopilotKit) and [`useAgent`](/reference/react-native/hooks/useAgent), reads the configured client from context.

Importing the package auto-installs the [polyfills](/reference/react-native#polyfills) CopilotKit needs on Hermes, so you do not have to import them manually before using the provider. One thing it cannot do for you: its `crypto.getRandomValues` falls back to `Math.random`, which is not cryptographically secure. For a secure one, import `react-native-get-random-values` on the first line of your entry point, before any CopilotKit import; once a CopilotKit module has loaded, the fallback stays and the secure import does nothing. See [Polyfills](/react-native#polyfills) in the guide.

<Callout type="info">
  Cloud features (`publicLicenseKey` and other license-gated features) are not yet
  supported on React Native. Point `runtimeUrl` at a self-hosted runtime.
</Callout>

<Callout type="info">
  Native iOS and Android applications do not have a built-in Inspector yet. The
  browser Inspector requires a DOM and is intentionally excluded from the React
  Native dependency graph, so this provider does not expose an inspector prop.
</Callout>

## Import [#import]

```tsx
import { CopilotKitProvider } from "@copilotkit/react-native";
```

## Props [#props]

<PropertyReference name="children" type="ReactNode" required>
  The components rendered within the provider.
</PropertyReference>

<PropertyReference name="runtimeUrl" type="string" required>
  URL of the CopilotKit runtime endpoint, e.g.
  `https://your-server/api/copilotkit`. Use your machine's LAN IP (not
  `localhost`) when testing on a physical device.
</PropertyReference>

<PropertyReference name="headers" type="Record<string, string> | (() => Record<string, string>)" default="{}">
  Custom headers sent with every runtime request. Pass a function to compute
  headers lazily (e.g. to attach a fresh auth token). The function is called
  when the provider renders, not per request. See
  [Frontends: React Native](/frontends/react-native#provider-options) for the
  rotating-token pattern.

  The web provider's builder runs at send time and also accepts an async
  function. Neither is supported here yet: only a sync function, evaluated at
  render, works on React Native.
</PropertyReference>

<PropertyReference name="credentials" type="RequestCredentials">
  Credentials mode for fetch requests (e.g. `"include"` for HTTP-only cookies
  in cross-origin requests).
</PropertyReference>

<PropertyReference name="messageFilter" type="(messages: Message[], context: { agentId: string }) => Message[]">
  Rewrites the message list sent to the agent on every run.

CopilotKit sends the whole thread with each request. Your agent can already
store the conversation, for example in a LangGraph checkpointer, a Mastra memory
store, or a Strands `SessionManager`. If it does, most of that payload is waste.
An agent that merges the inbound list with its own store can also show the model
every turn twice.
On a mobile connection the payload cost is felt sooner.

Return the messages to send:

```tsx
<CopilotKitProvider
  runtimeUrl="https://your-server/api/copilotkit"
  messageFilter={(messages) => messages.slice(-1)}
>
  <App />
</CopilotKitProvider>
```

The filter changes the request body only. The transcript the UI renders is
untouched, so the chat still shows the full conversation. Broken tool-call pairs
are repaired before the request goes out, so a filter this blunt cannot strand a
tool result mid-approval.

Agents reached through your CopilotRuntime honor this. An agent your app
constructs itself and passes in directly does not. CopilotKit Intelligence runs
and suggestion runs are never filtered.

</PropertyReference>

<PropertyReference name="useSingleEndpoint" type="boolean">
  Whether the runtime uses a single-route endpoint. Leave unset to auto-detect.
</PropertyReference>

<PropertyReference name="properties" type="Record<string, unknown>" default="{}">
  Custom properties forwarded to agents on every run (e.g. user metadata or
  LangGraph Platform `authorization`).
</PropertyReference>

<PropertyReference name="onError" type="(event: { error: Error; code: CopilotKitCoreErrorCode; context: Record<string, any> }) => void | Promise<void>">
  Error handler called when CopilotKit encounters an error. Fires for all error
  types: runtime connection failures, agent errors, and tool errors. If not
  provided, errors are logged to `console.error`.

```tsx
<CopilotKitProvider
  runtimeUrl="https://your-server/api/copilotkit"
  onError={(event) => {
    console.error(`[${event.code}]`, event.error.message, event.context);
  }}
>
  <App />
</CopilotKitProvider>
```

</PropertyReference>

<PropertyReference name="debug" type="DebugConfig">
  Enable debug logging for the client-side event pipeline. Pass `true` to log
  event and lifecycle summaries. Pass `{ verbose: true }` to log full event
  payloads.
</PropertyReference>

<PropertyReference name="defaultThrottleMs" type="number">
  Default throttle interval (ms) for `onMessagesChanged` / `onStateChanged`
  subscriptions. Individual hooks and components can override this with their
  own `throttleMs`.
</PropertyReference>

## Usage [#usage]

```tsx
import { CopilotKitProvider } from "@copilotkit/react-native";
import { SafeAreaProvider } from "react-native-safe-area-context";
import { ChatScreen } from "./ChatScreen";

export default function App() {
  return (
    <SafeAreaProvider>
      <CopilotKitProvider runtimeUrl="https://your-server/api/copilotkit">
        <ChatScreen />
      </CopilotKitProvider>
    </SafeAreaProvider>
  );
}
```

## Behavior [#behavior]

- **Auto-polyfills**: importing the package installs the Web API polyfills CopilotKit relies on (`ReadableStream`, `TextEncoder`, `crypto.getRandomValues`, `DOMException`, `location`) before any CopilotKit code runs. Each polyfill installs only when its global is missing, so a secure `crypto.getRandomValues` from `react-native-get-random-values` must be imported first, on the first line of the entry point.
- **Shared render-tool registry**: the provider instantiates the CopilotKit client whose renderer registry is shared with the rest of CopilotKit. Render functions registered by [`useRenderTool`](/reference/react-native/hooks/useRenderTool), [`useFrontendTool`](/reference/react-native/hooks/useFrontendTool) or [`useComponent`](/reference/react-native/hooks/useComponent) write into that one registry, so they and [`useRenderToolCall`](/reference/react-native/hooks/useRenderTool#rendering-a-tool-call-outside-the-chat) work anywhere below the provider. There is no second registry and no extra provider to mount for rendering.
- **Stable references**: header functions and `properties` are memoized internally to avoid effect churn on re-render.
