Drive app tools without shipping debug UI

The cordierite package is the operator side of Cordierite: run a TLS-terminated WebSocket host, create bootstrap sessions, and list, inspect, and invoke tools registered in the React Native app—so developers, QA, and agents can steer state from a terminal or script instead of hidden in-app debug menus.

Why use this package

• Host + session flow: host serves wss:// with a certificate generated from your private key and the resolved local IP; the app follows the deep link and claims a short-lived pending session.
• Tooling from the shell: tools and invoke talk to the device-side registry once the session is active—same conceptual surface automation uses.
• Fits production-minded apps: the app still only exposes what you register; trust boundaries are pins + TLS on the client (see HANDSHAKE.md).

Security notes

• You hold the private key for the host cert; the app pins the matching SPKI—no cleartext control plane, no trust in “just” the deep link or LAN.
• Bootstrap payloads are hints; authorization to speak to your host comes from TLS + pinning, not from payload secrecy alone.

Key setup

Generate a host key with:

cordierite keygen

The command writes an unencrypted PEM private key (PKCS#8) and prints the exact sha256/... SPKI fingerprint your app should place into cliPins. Use the generated file with cordierite host --tls-key ....

Commands (overview)

| Command | Role | | --- | --- | | host | Start the Cordierite wss:// host (generated cert, private key, scheme, optional open-on-macOS). | | connect | Validate a base64url binary v1 bootstrap payload. | | keygen | Interactively generate a host private key and print the app fingerprint for cliPins. | | session | Show the currently active host session. | | tools | List tools on the connected device or inspect one by name. | | invoke | Invoke a device tool with JSON input. |

Global options include --json for machine-readable output. See cordierite --help after install.

Programmatic use

The package exports runCli, createCli, and command helpers from src/index.ts so you can embed the same behavior in Node, Bun, Deno, or other JS runtimes that can execute the bundle and open TLS sockets.

Related packages

• @cordierite/react-native — native app client + Expo plugin.
• @cordierite/shared — shared library used by the CLI and React Native integration (dependency of this package).

Documentation

• Handshake & security model
• Monorepo README

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! 🔥