Tools and state from outside the app—without debug menus

This package is the native client for Cordierite. Your app registers tools in JavaScript; developers, testers, and agents invoke them from a CLI or host after the app opens a bootstrap link and completes a pinned wss:// handshake. You get production-grade transport (TLS + SPKI) instead of burying debug-only screens in the UI to flip state or trigger flows.

Why use it

• No in-app debug chrome: influence screens, flags, fixtures, and flows from the host, not from hidden menus shipped to users.
• Same path for people and automation: CLI for devs/QA, agents for scripted or LLM-driven control—both use tool calls after session claim.
• Production-capable: ship the client in real builds when your pins and operational model say it is acceptable; connectivity still requires a trusted host, not public anonymous access.

Security highlights

• TLS required for the Cordierite socket; pins are SHA-256 over SPKI (sha256/...) so only your host keys match.
• Optional allowPrivateLanOnly: when enabled, bootstrap must target a local IPv4 address (RFC1918 private ranges or 127.0.0.1)—a dev-hardening switch, not a claim that Cordierite is LAN-only.

Getting started

[!NOTE] Use a development build or bare native app. Expo Go is not enough—this library ships native code and pinning configuration.

Install with your package manager (npm, yarn, pnpm, …). Add the @cordierite/react-native config plugin to Expo config with cliPins (required) and optionally allowPrivateLanOnly; then run your usual prebuild so plist and manifest receive the values. For bare React Native, autolink the module and set the equivalent native keys—field names and semantics mirror the plugin (see app.plugin.js).

Generate a matching host key and pin with:

cordierite keygen

Use the printed fingerprint value verbatim in cliPins.

Bare React Native — native keys

iOS Info.plist:

| Key | Purpose | | --- | ------- | | CordieriteCliPins | String array of sha256/... SPKI pins | | CordieriteAllowPrivateLanOnly | Boolean; if true, bootstrap host must be a local IPv4 address |

Android <application> meta-data:

| Name | Purpose | | --- | ------- | | com.callstackincubator.cordierite.CLI_PINS | JSON array string of pin values | | com.callstackincubator.cordierite.ALLOW_PRIVATE_LAN_ONLY | "true" / "false" |

Empty or missing pins fail at configuration time. Wire deep links so the OS can open your app with the host’s bootstrap URL.

Bootstrap connection: importing this package registers React Native Linking listeners that watch for URLs with a cordierite query parameter, parse the binary v1 payload, and call connect when the client is idle. You do not need your own Linking handler for the default flow.

Errors: use addCordieriteErrorListener if you want callbacks when bootstrap parsing or that automatic connect fails.

Tools: call registerTool({ ... }) with Standard Schema compatible inputSchema and outputSchema values plus a handler so the host can invoke your tools after the session is active. zod v4 works well here and is used in the playground example.

import { registerTool } from "@cordierite/react-native";
import { z } from "zod";

registerTool(
  {
    name: "sum",
    description: "Add two numeric values",
    inputSchema: z.object({
      a: z.number(),
      b: z.number(),
    }),
    outputSchema: z.object({
      total: z.number(),
    }),
    handler: async ({ a, b }) => ({
      total: a + b,
    }),
  },
);

Platform compatibility

| Platform | Support | | --- | --- | | iOS | 15.1+ (Cordierite.podspec), New Architecture | | Android | Autolinked, New Architecture | | Web | Stub only |

Made with ❤️ at Callstack

cordierite is an open source project and will always remain free to use. If you think it's cool, please star it 🌟. Callstack is a group of React and React Native geeks, contact us at [email protected] if you need any help with these or just want to say hi!

Like the project? ⚛️ Join the team who does amazing stuff for clients and drives React Native Open Source! 🔥