SDKs
Use an SDK when your code should talk directly to a Thalovant hub.
The Thalovant API is the control plane at https://api.thalovant.com. It discovers hubs and creates client identities. The SDK is the data plane. It sends runtime traffic to the hub over WSS, HTTPS, or MQTT over TLS.
Best First Path
Section titled “Best First Path”- Pick the SDK for your runtime. Python, Node.js, Go, Rust, Kotlin, Swift, and .NET expose the same core behavior. Embedded C is a protocol library for devices that bring their own transport.
- Use the hosted API. Start with
https://api.thalovant.com. - Create one client identity per app, device, or agent. Store the returned identity in a secret store or protected SDK config file.
- Connect with WSS first. It is the default realtime path for public clients, and it is the only data-plane protocol in the Kotlin, Swift, and .NET SDKs.
- Add HTTPS, MQTT, or browser origin access only when needed. Create a fresh identity after enabling a new protocol on the hub, and request an approved SDK Origin before calling the API from a customer-owned browser app.
Choose A Language
Section titled “Choose A Language”| Language | Install | Best fit |
|---|---|---|
| Python | pip install thalovant |
Agents, tools, notebooks, tests, and service workers. |
| Node.js | npm install @thalovant/sdk |
TypeScript services, bots, scripts, web backends, and bundled browser apps. |
| Go | go get github.com/thalovant/thalovant-go-sdk |
Gateways, CLIs, small services, and long-running workers. |
| Rust | cargo add thalovant |
Strict clients, embedded work, and reliability-focused services. |
| Kotlin | implementation("com.thalovant:thalovant-sdk:0.7.1") |
JVM services and Android apps. |
| Swift | SwiftPM package from the GitHub repository | iOS and macOS apps; Linux requires a WebSocket-capable Foundation runtime. |
| C# / .NET | dotnet add package Thalovant.Sdk |
Enterprise .NET services and Unity apps. |
| C | Vendored source pinned to a release tag | Microcontroller and embedded devices that bring their own MQTT or WebSocket client. |
Capability Tiers
Section titled “Capability Tiers”Not every SDK covers every protocol yet. Pick the tier that matches your runtime needs.
| Tier | SDKs | Data plane | Control plane |
|---|---|---|---|
| Full | Python, Node.js, Go, Rust | WSS, HTTPS, and MQTT over TLS | MFA sign-in, device login, API token auth, provisioning, and typed operation polling |
| WSS-only | Kotlin, Swift, .NET | WSS only; requesting HTTPS or MQTT raises a clear unsupported-protocol error | MFA sign-in, device login, API token auth, provisioning, and typed operation polling |
| Protocol library | Embedded C | None built in; you bring the MQTT or WebSocket client and the library supplies identity parsing, topics, encryption, and wire framing | None |
Browser apps use the Node SDK behind a bundler: the control plane and the WSS and HTTPS data plane work in web bundles, while MQTT and identity file helpers stay Node-only. See Browser usage in the Node SDK.
Shared Runtime Features
Section titled “Shared Runtime Features”The seven high-level SDKs provide these features within their supported transports. Embedded C exposes the corresponding wire building and parsing primitives; the application owns the connection, scheduling, collection, and cancellation.
| Feature | Python, Node.js, Go, Rust | Kotlin, Swift, .NET | Embedded C |
|---|---|---|---|
| Sign-in, MFA, device login, tokens, provisioning, operation polling | Supported | Supported | Application supplies control plane |
| Hub-addressed skill management and history | Supported; affects the attached shared runtime group | Supported; affects the attached shared runtime group | Application supplies control plane |
| Ask, scoped query/cascade replies, raw events, action/code inputs | Supported | Supported over WSS | Frame builders and reply classification |
| Conversations, event waits and streams | Supported; Node streams use callback subscriptions | Supported; streams buffer at most 64 events | Application owns collection and session state |
| Intent listing, describes and names-only fallback | Supported | Supported | Request builders and response readers |
| Fallback handlers and conservative language availability | Inventory fields in Python/Node; additive capability wrapper in Go/Rust | Inventory fields with mayAnswer in Kotlin/Swift and MayAnswer in .NET |
Fallback frames and response classification; application computes availability |
| Recognized language, ordered pipeline and request location hints | Native request options/helpers | Native request helpers | Payload/frame builders with hints and location builder |
| Embedded skill audio and reported language | Ordered speech/audio, 4 MiB clip / 16 MiB reply bounds | Same bounds and ordered media within WSS replies | Correlation-aware decoder and caller-owned budget/collection |
| Speakable intent examples | Optional rendering and source-priority ranking | Optional rendering and source-priority ranking | Pattern renderer; application ranks and deduplicates |
| Guarded runtime configuration merge | Revision GET/PUT; at most three attempts, only 412 retries | Same guarded merge and explicit replacement | Application supplies control plane |
| Connection information, health and diagnostics | Supported; details differ by SDK | Local authenticated transport state | Application supplies diagnostics |
| Trust persistence and reconnect authentication | SDK-owned state, configurable storage | SDK-owned state, configurable storage | Caller-owned persistent state and buffers |
An intent miss can precede delayed speech. By default, Ask starts a fixed 250 ms settlement window on first nonempty speech, or a fixed five-second empty wait on first handled/soft-miss without speech. Callers may override these durations. Later fragments do not restart settlement. Both windows are clipped to the original request deadline; collected speech is returned when it expires. A query collector waits for hive.query.complete or its deadline. Policy denial and explicit query timeout freeze any partial reply immediately, including while a send is retiring. Reconnection never replays an application request automatically. See runtime recipes and intent discovery.
CI Coverage And Platform Limits
Section titled “CI Coverage And Platform Limits”| Consumer | Runtime and platform checks | Security and interoperability checks |
|---|---|---|
| Python | Python 3.10–3.14; transport, lifecycle and inventory regressions | Runtime dependency audit with pip-audit; Python CodeQL |
| Node.js | Node.js 20, 22 and 24; lifecycle and browser-scope regressions | Dependency audit; JavaScript/TypeScript CodeQL; independent Noise fixtures |
| Go | Go 1.26 and 1.27; Linux, macOS and Windows race tests | govulncheck; 60-second parser fuzzing; Go CodeQL |
| Rust | Rust 1.88 minimum; stable Linux, macOS and Windows; format and Clippy | RustSec cargo audit; Rust CodeQL; independent Noise vectors and adverse transport tests |
| Kotlin | JVM 17 and 21 | Java/Kotlin CodeQL; independent Node WSS XX→KK and query exchanges |
| Swift | Swift 5.10 Linux unit tests and macOS tests; WebSocket-enabled Linux interop runtime | Swift and C CodeQL; source provenance checks; independent Node XX→KK with concurrent readiness callers |
| .NET | .NET 8 and 9 tests on Linux and Windows; net8.0 and netstandard2.1 packages |
C# CodeQL; independent Node WSS XX→KK and query exchanges |
| Embedded C | GCC, Clang and 32-bit builds | Address/undefined-behavior sanitizers; 120-second fuzzing; C CodeQL |
| MCP | Node.js 20, 22 and 24; tool and identity-ownership regressions | Dependency audit; JavaScript/TypeScript CodeQL; origin-bound credential tests |
These checks do not establish Android or Unity device coverage, or test every Linux Foundation/libcurl build. Swift on Linux needs WebSocket support in its Foundation networking runtime. Local healthcheck and doctor results describe the connection; they do not guarantee that every skill or external dependency is healthy. Release workflows also produce package provenance and SBOM artifacts. See each SDK repository’s CI for the exact current job results.
API Credential Security
Section titled “API Credential Security”Configure the final API URL: SDK control-plane requests refuse redirects, including redirects that would resend a login password. Authenticated requests and request bodies require HTTPS. These calls can use HTTP only on explicit localhost, 127.0.0.1, and [::1] development endpoints; a hostname that merely resolves to a private address does not qualify. API URLs cannot embed userinfo. Device login validates both verification URLs before showing a prompt, invoking a browser callback, or polling. URLs must use HTTP(S), include a host, and contain no userinfo, raw whitespace, or control characters.
The .NET security patch changes custom HTTP integration: credential-bearing calls cannot use an arbitrary injected HttpClient. Use the SDK-owned client or the supported handler injection described in the .NET guide. Preserve private CA settings when configuring a custom transport.
Transport Security
Section titled “Transport Security”A hub running HiveMind-core 5.x accepts exactly one transport key exchange: the
v3 Noise handshake. The pre-shared
crypto_key and its AES path are gone, there is no cleartext fallback, and a
connection that cannot complete the handshake is closed with WebSocket code
1008.
Nothing new has to be provisioned. v3 derives its Noise pre-shared key from the
client password your identity already carries, salted with the hub’s node id.
Every SDK below implements v3 Noise. Kotlin, Swift, and .NET remain WSS-only; embedded C supplies the protocol implementation and requires your transport. Older pre-shared-key releases cannot connect to a v3-only hub, even if the identity still contains crypto_key.
Use fresh request and query IDs for each logical operation. Active duplicate collectors are rejected within the documented client scope; session IDs may be reused for a conversation.
Keep the client’s static key and server pins in private, persistent storage. Reuse that state on reconnect and after a process restart. A failed handshake never authorizes automatic pin replacement: verify a server-key rotation before deliberately changing trust. Use a distinct client identity for each simultaneously running client process.
Supported Versions
Section titled “Supported Versions”This coordinated package set supports the v3-only runtime. Each connection selects a mutually offered suite and fails if none is supported.
| Consumer | Supported package version | Noise suites | Registry and runtime |
|---|---|---|---|
| Python SDK | thalovant 0.7.5 |
ChaChaPoly and AESGCM | PyPI; Python 3.10 or newer |
| Node.js SDK | @thalovant/sdk 0.7.1 |
ChaChaPoly and AESGCM | npm; Node.js 20 or newer, or a supported browser bundle |
| Go SDK | github.com/thalovant/thalovant-go-sdk v0.9.1 |
ChaChaPoly and AESGCM | Public Go module; Go 1.26 or newer |
| Rust SDK | thalovant 0.9.0 |
ChaChaPoly and AESGCM | crates.io; Rust 1.88 or newer |
| Kotlin SDK | com.thalovant:thalovant-sdk 0.7.1 |
ChaChaPoly and AESGCM | Maven Central; JVM 17 or a compatible Android toolchain |
| Swift SDK | thalovant-swift-sdk 0.7.1 |
AESGCM | Swift Package Manager; Swift 5.9 or newer; see the Linux runtime requirement |
| .NET SDK | Thalovant.Sdk 0.7.1 |
AESGCM | NuGet; net8.0 and netstandard2.1; Unity requires an explicit private state store |
| Embedded C library | thalovant-embedded-c v0.6.1 |
AESGCM | Immutable Git tag and release archives; C99, caller-owned transport and buffers |
| MCP server | @thalovant/mcp-server 0.5.1 |
Via Node SDK 0.7.1 | npm, GHCR, and the MCP Registry |
All suites use X25519 and SHA-256: their full names are 25519_ChaChaPoly_SHA256 and 25519_AESGCM_SHA256. All eight SDKs implement XXpsk2 for first contact and KKpsk0 for a pinned peer. TLS protects endpoint admission and broker credentials in addition to Noise protecting hub messages.
MCP runtime tools open hub connections through the Node SDK over WSS, HTTPS, or MQTT over TLS. The MCP server’s stdio and Streamable HTTP options describe how an agent calls MCP tools; they are separate from the selected hub protocol.
All control-plane calls use the backward-compatible /api/v1 boundary. Additive server fields are safe for older SDKs because clients ignore fields they do not understand. A client that needs a newly added capability must use the minimum version listed in that capability’s release note.
The MCP server uses the Node SDK and is released after its compatible SDK version. MCP 0.5.1 uses @thalovant/sdk 0.7.1 and is published with aligned npm, OCI, and MCP Registry metadata.
SDKs with a control plane support signing in without a password through login_with_browser and its language-native equivalents. Each language guide also documents direct API token authentication. See Sign In Without A Password.
SDKs with a control plane can also create hubs, runtime groups, and skill installs from code. Every SDK with a control plane ships the same provisioning and skill-discovery surface, and the MCP server exposes it as tools. See Provision Hubs.
The hub intent inventory, which lists what a hub can be asked over the client’s own session, is in every published SDK. The table below records the first version for each SDK. See What Can My Hub Be Asked?.
| SDK | First version with the inventory |
|---|---|
| Python | thalovant 0.4.36 |
| Node.js | @thalovant/sdk 0.2.38 |
| Go | github.com/thalovant/thalovant-go-sdk v0.3.13 |
| Rust | thalovant 0.3.0 |
| Kotlin | com.thalovant:thalovant-sdk 0.1.8 |
| Swift | thalovant-swift-sdk 0.1.8 |
| .NET | Thalovant.Sdk 0.1.12 |
| Embedded C | thalovant-embedded-c v0.2.0 |
A hub that accepts the listing and answers it with an error was read as an empty hub in the first release of several ports. The first versions that report it as an error are: Python 0.4.40, Node.js 0.2.39, Go v0.3.14, Rust 0.3.1, Kotlin 0.1.8, Swift 0.1.9, .NET 0.1.13, and embedded C v0.3.0.
How SDK Access Works
Section titled “How SDK Access Works”- Discover a hub. Public hub discovery can be used before sign-in.
- Sign in for private API actions. Creating client identities requires API access on the workspace. Use a password login, a browser-approved device sign-in, or a scoped API token.
- Create a client identity. The SDK stores the returned identity locally or in your secret store.
- Connect to the hub. Runtime traffic goes directly to the hub endpoint.
- Send a request. Start with one
askcall, then add sessions, context, actions, or rich output.
Browser Origins
Section titled “Browser Origins”Browser apps on customer-owned domains need an approved SDK Origin before cross-origin SDK or API calls are accepted.
Approval is exact-origin based and non-credentialed. It allows requests from a reviewed origin, but it does not allow dashboard cookies, refresh-session headers, setup links, or long-lived client identities to be exposed in browser bundles.
Protocols
Section titled “Protocols”| Protocol | Use it when | Notes |
|---|---|---|
| WSS | You want the default public realtime path. | Best first choice for agents and clients that may listen for events. Supported by all client SDKs; embedded C requires your transport. |
| HTTPS | You want request-response calls, health checks, CLIs, or jobs. | Must be enabled on the hub before public clients can use it. Python, Node.js, Go, and Rust only. |
| MQTT over TLS | You want broker-mediated device or edge traffic. | Requires per-client broker credentials and topic access. Python, Node.js, Go, and Rust only; Node.js supports it outside browsers. |
What To Keep Secret
Section titled “What To Keep Secret”Every client identity is secret. Store it like a password.
Do not put identity files, access keys, passwords, broker passwords, setup links, or crypto keys in browser bundles, public repos, screenshots, logs, or support tickets.
Production Checklist
Section titled “Production Checklist”| Check | Good default |
|---|---|
| API base URL | https://api.thalovant.com |
| First runtime protocol | WSS |
| Browser usage | Use SDK Origins for reviewed browser domains. Keep secrets on a backend. |
| Identity storage | Use a secret manager, CI secret, mounted secret file, or ~/.config/thalovant/config.yaml with mode 600. |
| MQTT | Use mqtts://, per-client credentials, and SDK-managed topics. |
| Noise state | Preserve private static keys and verified server pins across restarts. Use a distinct identity for concurrent client processes. |
| Rotation | Verify server-key rotations before changing a pin; replace client credentials by provisioning a new identity. |
| Logs | Redact identity JSON, broker passwords, API tokens, and crypto keys. |
Skill-management coverage
Section titled “Skill-management coverage”Python, Node, Go, Rust, Kotlin, .NET and Swift provide hub-addressed skill list, history, install, update and removal, alongside the existing runtime-group skill upsert/removal and hub/runtime configuration and release helpers. MCP exposes the corresponding tools. Embedded C remains a transport-independent wire/crypto library without a provisioning HTTP client.
Hub-addressed skill calls change the attached runtime group and therefore affect all hubs sharing it. See the language page for operation waiting and resumption.
If you already know your language, open the SDK page.
Use SDK Functions when you need method names across languages. Use MQTT when the client connects through the broker. If you are designing a shared SDK feature, use the SDK Contract. If you are adding a language, start from the v3 Noise Handshake — a client that cannot complete it cannot connect.
Last reviewed: September 13, 2026. Review this page when an SDK or MCP package version, registry, compatibility requirement, or install command changes.
Locale-aware sentence listings are available in Python 0.7.4 with its listing extra, Node 0.7.1, Go 0.9.1 and Rust 0.9.0, Kotlin, Swift and .NET 0.7.1, and MCP 0.5.1. The managed ports bundle the same language rules. Raw examples remain the default; sentence rendering adds locale samples, capitalization and punctuation. Embedded C keeps its caller-buffer pattern helper and does not bundle locale data or regional matching tables.
Managed sessions and presentable inventories
Section titled “Managed sessions and presentable inventories”Python, Node, Go, Rust, Kotlin, .NET, and Swift provide managed hub sessions, presentable skill/intent inventories, and optional private caches. Sessions keep subscriptions across connection replacement and never replay an admitted action automatically. Application code owns connection-factory budgets and probe scheduling. The Python guide and each language guide explain the API and migration details.
MCP exposes the presentation model in its inventory tool while keeping each call’s identity lease separate. Embedded C retains its caller-buffer, transport-agnostic core; managed sessions, disk caches, and locale databases belong to the host application. Transport support remains as listed above.
Reply claim metadata
Section titled “Reply claim metadata”The current SDK releases expose ordered pipeline and skill IDs and an advisory claim result. This lets clients distinguish a fallback-only answer from a matched intent without discarding the answer. Older successful hubs without stamps remain compatible. See each SDK’s reply-claims section for its idiomatic API; embedded C keeps caller-owned storage and MCP exposes the fields in its runtime summary.