Skip to main content
The SDK is a normal npm package with no build step and no install-time compilation.
The package is ESM only and ships its own .d.ts declarations.

​
Node version

The SDK requires Node ^20.19.0 || >=22.12.0. That range is narrower than it looks, so read it literally:

​
Why the floor exists

The floor is a crypto requirement, not a networking one. The HPKE wrap engine and the hashing and curve libraries under it draw randomness from globalThis.crypto.getRandomValues, read lazily at call time. Node 19 and later define globalThis.crypto in ESM. Node 18 does not. That produces a failure with unhelpful timing. On Node 18 the SDK imports fine, and a bot with an existing keystore can even log in fine, because importing a stored identity and unwrapping a key consume no randomness. It then dies later, at the first identity generation or the first message encrypt, with crypto.getRandomValues must be defined. login() pre-empts that. It checks the runtime as its first step and throws a CloakEnvironmentError carrying a remedy:
If you want to assert the range yourself, the SDK exports assertSupportedRuntime() and the SUPPORTED_NODE string.
If you hit that error on a host image you did not build, check that the process really runs the Node you installed. process.version is the value the guard read, and generateDependencyReport() prints it.

​
What npm install does not do

The default connection is a plain wss:// WebSocket. Every dependency the SDK actually loads is pure JavaScript: ws for the socket, and the @noble ciphers, curves, and hashes packages for crypto. That gives you a short list of things you do not need:
  • No compiler, and no node-gyp step. Nothing compiles at install time.
  • No native addon in the import graph on the default path.
  • No glibc floor, so musl hosts like Alpine work.
  • No Dockerfile, no build step, and no git dependency.
npm i && node bot.js is the whole deployment.

​
The two optional extras

The package declares three optionalDependencies, covering two opt-in features. Neither is imported unless you ask for it. Opt into the first with transport: 'webtransport' in ClientOptions, and into the second by attaching a VoiceMediaSession. The voice control plane (joining a channel, reading the roster) needs neither: it rides the same wire as everything else.
optionalDependencies means “a failure to install does not fail your install”. It does not mean “does not install”. npm pulls all three by default and skips only a platform it has no prebuild for, so roughly 19 MB of voice engine lands in a text-only bot’s node_modules too.
Nothing imports either extra unless you opt in, so a missing or broken build costs you disk, not runtime compatibility. To skip them outright:
Reach for Docker only if you need one of these two. Otherwise it buys you nothing.
Publishing voice audio needs a one-line patch to @livekit/rtc-node in your own project, because the upstream package cannot install a per-participant frame key as published. The patch file ships inside the SDK tarball. See Voice runtime and troubleshooting.

​
Supported hosts

Any host running a supported Node version works: Railway, Fly, Render, a systemd unit on a VPS, a Raspberry Pi, a container of your own. The SDK opens one outbound wss:// connection and needs no inbound port. Two host decisions matter more than the rest:
  • The token comes from the environment. Use a secret manager, a platform secret, or --env-file. Anyone holding the token is a full encrypted member of every server your bot is in.
  • The keystore must survive restarts. On a host with a writable disk, point keystorePath at a mounted volume, not at the ephemeral container filesystem. On a host with no writable disk, use a keystore adapter and put its written blob in your platform’s secret store. See Keystore backends.

​
What the other side needs

Your bot never generates a server’s conversation key. A human member’s client wraps that key and uploads it, and this SDK produces and accepts only the current HPKE wrap format. So the humans in your bot’s servers must be on a Cloak client build that ships it. If one is not, that member’s key handoff fails, and the SDK names the offending peer in a warning rather than failing silently.

​
Checking an install

The SDK ships a dependency report that tells you what your host actually resolved: the Node version and whether it satisfies the range, the platform, architecture and glibc, whether a secure random source is reachable, the resolved crypto library versions, and which optional natives are present. It opens no socket, spawns no process, and loads no native addon. It returns the report as a string rather than printing it, so print it yourself:
Do not run it with node -e or node -p. Those modes define a crypto global in their own eval bootstrap that a normal process would not have, and the leak reaches modules imported from them. The report cannot tell that apart from a real one, so it will tell you a secure RNG is available on a runtime that has none. Run it from a file.
dependencyReport() returns the same data structured, and hasSecureRandom() runs just the RNG probe. Paste the string form into any bug report.

​
License

The SDK is proprietary software owned by Cloak Software LLC. It is free to install and use for building bots, and the full grant is in the LICENSE file shipped inside the package. Two limits are worth knowing before you start:
  • You may not redistribute or republish the SDK, or a thin wrapper around it, as a competing library.
  • Your use is also governed by the Bot Developer Terms.

​
Next

Quickstart

A running bot in about five minutes.

Keys and the keystore

Why a keystore is mandatory, and what it holds.

Transports and endpoints

The default WebSocket lane, the WebTransport opt-in, and the endpoints.

Deploying a bot

Hosts, secrets, and keeping the keystore durable.