Skip to main content
The TypeScript SDK (@rkat/sdk) brings Meerkat agents into Node.js applications. Create and resume sessions, stream typed events, schedule work or coordinate teams through Session, DeferredSession and Mob handles. It spawns a local rkat-rpc subprocess using the same runtime as the CLI and service APIs. For agents that run in the browser itself, use the Web SDK.

Getting started

1

Install the SDK

The SDK needs Node.js 20.19+ or 22.12+ (engines.node). It ships only an ES module, so require() from CommonJS relies on Node’s require(esm), which those releases enable by default; Node 21 and 22.0-22.11 are outside the range.
2

Install the RPC binary

Homebrew installs rkat-rpc with the other binaries. Without Homebrew, download the rkat-rpc release archive for your platform and put it on your PATH (see Linux without Homebrew). Without one, the published SDK downloads the rkat-rpc release binary of its own version for the current platform and verifies it against the digests the package pins (see The rkat-rpc binary), so a manual binary install is optional unless you want to control the binary path yourself. Contributors working from a checkout can build it with make build instead.You also need an API key for at least one LLM provider (e.g. ANTHROPIC_API_KEY).
3

Configure tsconfig

The SDK is ESM. Your tsconfig.json must use Node16 module resolution:
4

Connect and run


Method overview

MeerkatClient methods

Schedule methods parse the canonical flattened response shape: planning, timestamps, labels, and other schedule configuration are top-level fields, not a nested config, and internal machine_state is never public. Missing or malformed schedule, occurrence, and tool arrays—or required facts within their entries—throw MeerkatError with INVALID_RESPONSE instead of becoming empty or zero-valued results.

Auth wrappers

The SDK also exposes the auth-profile wrappers from the RPC surface:
  • authProfileList(...), authProfileGet(...), authProfileCreate(...), authProfileDelete(...)
  • authLoginStart(...), authLoginComplete(...), authLoginDeviceStart(...), authLoginDeviceComplete(...), authLoginProvisionApiKey(...)
  • authStatusGet(...), authLogout(...)
  • realmList(...), realmGet(...)
  • sendPeerResponseTerminal(...)
  • mcpAdd(...), mcpRemove(...), mcpReload(...)
  • getBlob(...), listSkills()
  • getRuntimeHostInfo(), getRuntimeHostCapabilities(), getRuntimeHostHealth()
Every public TypeScript RPC wrapper binds its request and response transport boundary to generated RPC-schema contracts. In 0.8.24, generated names used by the job, approval, artifact, and durable-event declarations are not re-exported from the package root; callers can pass object literals matching the displayed method signature. Approval methods maintain audit records only. Requesting or deciding a record does not automatically gate, authorize, or execute an action. See JSON-RPC approvals for persistence and single-writer details. Auth profiles and credentials are realm-scoped. Login/provisioning yields an auth binding that can be referenced by SessionOptions.authBinding or a mob member spec without placing the provider secret in that spec. Remote hosts resolve bindings only within their authorized realm.

Generated assistant images

When a session model calls the built-in generate_image tool, generated images appear in committed history as SessionAssistantBlock entries with blockType === "image". The SDK preserves imageId, blobId, mediaType, width, height, revisedPrompt, and provider metadata.
Image-generation wire contracts are exported for integrations that inspect tool results directly: WireGenerateImageRequest, WireGenerateImageExecutionPlan, WireImageGenerationToolResult, WireImageOperationPhase, and WireAssistantImageRef.

Capability methods

Session methods

Live channel helper

RealtimeChannel and the old realtime convenience helpers are no longer part of the public SDK. Use LiveChannel.session(client, session.id, options?) for a session-bound wrapper around the live/* methods. The SDK returns a discriminated transport bootstrap from live/open; callers own the WebSocket or WebRTC connection. The example below requests WebRTC explicitly. For WebSocket, connect with liveWs: true and request transport: "websocket".
@rkat/sdk is Node-only and does not provide RTCPeerConnection. Keep the peer connection in a browser or inject a Node WebRTC implementation. Add an audio track or the meerkat.live data channel, call setLocalDescription, wait for ICE gathering to complete, then forward peer.localDescription.sdp to the Node process. Install the returned answer as the browser peer’s remote description. A media-less or pre-ICE SDP cannot establish the live channel.
The 0.8.24 answerLiveWebrtcOffer(...) convenience helper does not wait for ICE gathering and sends the original createOffer() SDP instead of the final local description. Use the direct client.liveWebrtcAnswer(...) exchange above for the canonical browser flow until the helper is fixed.
liveWebrtc: true passes the --live-webrtc process flag, which exists only when rkat-rpc was compiled with its non-default live-webrtc Cargo feature. The 0.8.24 release binary and a normal default-feature build do not include that flag. From the Meerkat repository, build an explicit binary with ./scripts/repo-cargo build -p meerkat-rpc --features live-webrtc, then put it on PATH or pass its path to new MeerkatClient(path).
Image keys are required, caller-stable, and session-scoped. See Live Channels for same-key replay, conflict handling, and reconnect hydration limits. seedMaxChars maps to live/open.seed_max_chars. Use a positive value to bound serialized seed messages and request a core-selected whole-turn suffix; omit it for the complete canonical seed. Every ordered System message must fit; an existing compaction summary may be retained, and any truncation reports degraded continuity. Canonical image identity, tombstone, and accounting sidecars remain complete. The server rejects zero.

Mob methods

Multi-host placement and host/grant mutation are trusted JSON-RPC operator surfaces, not agent-callable mob tools. Agent-callable spawn also cannot carry the Rust-only resume_from_role one-shot durable role-migration declaration.

MeerkatClient

Constructor

MEERKAT_BIN_PATH wins when set, then an explicit rkatPath, then rkat-rpc on $PATH. Otherwise the SDK downloads the release binary of its own version for the current platform and caches it in ~/.cache/meerkat/bin/rkat-rpc.

The rkat-rpc binary

The SDK runs MEERKAT_BIN_PATH, an explicit rkatPath and rkat-rpc on $PATH as they are: trusting a binary you chose is your decision. Only the download is verified. A published @rkat/sdk package pins the sha256 of every release archive it may download and of the rkat-rpc inside it: pinned when the package is built, from the release’s manifest, with each archive’s build attestation verified, and never fetched at download time. The download uses HTTPS only, redirects included, and refuses an archive over 256 MiB (BINARY_DOWNLOAD_TOO_LARGE). The archive is checked before anything is written or extracted, the binary before it is installed, and the cached binary again each time it is reused. A mismatch throws BinaryIntegrityError (code BINARY_INTEGRITY_MISMATCH, with asset, path, expectedSha256 and actualSha256): the SDK deletes what failed, runs nothing and does not fall back to another binary.
A source or git install of the SDK pins no digests and refuses to download, throwing MeerkatError with code BINARY_DIGEST_UNAVAILABLE. Build or install rkat-rpc yourself and put it on $PATH, or pass its path to new MeerkatClient(path) or set MEERKAT_BIN_PATH to a binary you trust.

connect()

Spawns rkat-rpc, performs initialize handshake, checks contract version compatibility, and fetches capabilities. Returns this for chaining.
realmId and isolated are mutually exclusive. If realmId is omitted and isolated is not set, the spawned rkat-rpc process uses its normal isolated-mode default rather than a shared default realm. Reuse realmId explicitly to share sessions and config across processes or surfaces. Set liveWs: true for the WebSocket live adapter; the SDK starts rkat-rpc with an ephemeral listener and live/open returns its URL/token bootstrap. Set liveWebrtc: true for the WebRTC bootstrap/SDP-answer path, using a binary built with the non-default meerkat-rpc/live-webrtc feature. When both are enabled, select the requested transport through LiveChannelOptions.transport.

createSession()

Creates a new session, runs the first turn with prompt, and returns a Session object. The Session holds the last RunResult and exposes convenience accessors for the most recent text, usage, and tool call counts.

createSessionStreaming()

Creates a new session and returns an EventStream for the first turn. Iterate the stream to receive typed events as they arrive. The final RunResult is available on stream.result after iteration completes.

SessionOptions

All fields are camelCase:
createDeferredSession(...) reuses SessionOptions, but the server rejects transientTurnContext when no immediate turn exists: pass it to the first turn instead. startTurn(...) and stream(...) take injectedContext, transientTurnContext, skillRefs, turnToolOverlay, additionalInstructions, keepAlive, model, provider, selfHostedServerId, systemPrompt, providerParams, and authBinding. The turn options also carry maxTokens, outputSchema, and structuredOutputRetries, but the server refuses them on a turn with INVALID_PARAMS: they are build settings, so set them on createSession(...) or createDeferredSession(...). reasoningEffort sets the session’s provider-neutral reasoning effort level. On createSession(...) (and the streaming and deferred variants) it is a level. On turn(...), stream(...), startTurn(...) and mobTurnStart(...) it is the turn’s tri-state: a level sets it from that turn on, { action: "clear" } removes it, and leaving it out keeps it. The client sends it only to a server whose contract is 0.9.15 or later and throws CapabilityUnavailableError otherwise, before anything is written: an older server ignores it on session/create and refuses it on a turn. A level the model or its route does not accept rejects the call with a MeerkatError whose code is "-32602" (invalid params); reasoningEffortRefusal(error) returns the typed refusal (requested, provider, model, route, reason, supported, facts, conflictingParam, conflictingLevel, transient), or undefined for any other error:
reason is one of the eight closed reasons (REASONING_EFFORT_REFUSAL_REASONS); transient is true only for supported_levels_unavailable. A refusal with a reason this SDK does not know is not parsed, and error.details keeps the data as sent. The route’s names and facts are advisory and kept as strings. route, supported and facts are always present in the refusal data: null when they have no value, never left out. One case is not recognisable by its data kind: a meerkat_resume of, or a meerkat_comms_send to, the session of a mob member that is not live, whose own build is refused for the level in its profile, is answered the generic agent error (-32013) with a message and no reasoning_effort_refused data. reasoningEffortReport(result) reads the reasoning_effort block of a run result (the level requested and one sent row per distinct resolution), and parseReasoningEffortResolution(...) the resolution run_started, run_resumed and request_reasoning_effort_resolved carry. A turn that would change the model identity of a session that has unfinished work is not queued behind that work (the rule of the JSON-RPC turn requests: Model settings on a busy session). It rejects at once with a MeerkatError whose code is "-32002" (session busy) and whose details are { kind: "reasoning_effort_change_needs_idle_session" }; nothing is stored for the turn. The one kind covers every cause. On a session that holds a provider-neutral level: a turn that sets, changes or clears the level, or that changes the model, the provider, the self-hosted server, the provider parameters or the auth binding (a level named inside providerParams replaces those parameters, so it is one of these even when the level is the same). On a session that holds no level: a turn that sets one. Plain turns, and turns that repeat the session’s level with reasoningEffort, queue as before. This is not a level refusal, so reasoningEffortRefusal(error) returns undefined for it; a level the model does not accept is still answered with its refusal first. Wait for the running turn’s answer, then send the turn again; do not poll. A later release is planned to queue such a turn.
grantGatedTools gates built-in tool families and tool names: the session mounts them hidden and refuses their calls until grantTool(sessionId, { family }, { durationMs }) or grantTool(sessionId, { tool }, { expiresAtMs }) opens them; see scoped tool grants. grantTool rejects with INVALID_ARGS, before sending, a target that names both or neither of tool and family, and a window that names both or neither of durationMs and expiresAtMs. The client sends a gate only to a server whose contract is 0.9.9 or later, and otherwise throws CapabilityUnavailableError: an older server would build the session with the gated tools ungated.

Session

createSession() resolves to a Session object that acts as the handle for subsequent turns on the same conversation. createSessionStreaming() instead returns an EventStream: after consumption, stream.result is the final RunResult and stream.sessionId is the created session’s identity. The stream does not construct a Session wrapper or expose its methods. Both creation paths use the canonical runtime session lifecycle.

Identity

Last-result shortcuts

These accessors always reflect the most recent completed turn:
session.usage is the cumulative token account for the whole session to date, not the last turn’s usage, and it keeps growing across turns. Never add successive readings together. See Usage accounting.

turn()

Sends another turn to the session and returns the RunResult. Also updates the session’s last-result shortcuts. maxTokens, outputSchema, and structuredOutputRetries are build settings: the server refuses them on a turn with INVALID_PARAMS, so set them when you create the session.
Known issue, noted 2026-11-13: in releases up to and including 0.9.14 (the first affected release differs by case: see the release page for the range of each), a turn that cannot be started can permanently destroy the mobs its session owns. See the known issue on the 0.9.14 release page for the affected releases, the cases and what to do.

stream()

Sends another turn and returns an EventStream, whose iterator is typed as AsyncIterable<StreamEvent>. The session’s last-result shortcuts are updated when iteration completes.
Injected context is durable ordered user-channel context immediately before the prompt. transientTurnContext carries request-only host facts and is not a transcript message.

interrupt()

Sends turn/interrupt for this session. Has no effect if no turn is running.

stopRun()

Sends turn/stop_run. It stops exactly runId (read it from the run_started event’s identity.run_id) and terminalizes every input already bound to that run, including durable steers that joined it. receipt.outcome is stopped (with contributors), not_current (the run is no longer current; nothing was touched), or not_stoppable. mob.stopMemberRun(agentIdentity, runId, reason) does the same for one mob member.

recallInput()

From 0.9.15.
Sends session/recall_input. It withdraws one input of the session, only while it is still queued: name it by the inputId its submit answered or by the idempotencyKey it was submitted under. The selector names exactly one of the two: one that names both or neither rejects with INVALID_ARGS before anything is sent. recall.outcome is abandoned (the input was queued and is now withdrawn: its terminal is cancelled and no run will take it; attempt_count is 0 when no run attempt was counted for it), not_queued (a run holds it: nothing was touched and the run is not interrupted; phase says where it is and run_id, when the runtime has one, names the run that holds it) or already_terminal (it already ended; terminal is its terminal class, cancelled for a second recall). The list of outcomes can grow: keep an outcome you do not know as it is (the method resolves with it unchanged and does not reject). An input the session does not hold rejects with the invalid-params code. The recall is session-level (any queued input of the session, whoever submitted it) and withdraws everything the queue coalesced into the input; see session/recall_input. A server that does not serve the method (0.9.0 through 0.9.14; an older server is refused when the SDK connects) answers method not found, and the call rejects with MeerkatError whose code is "-32601"; the method does not read the server’s contract version or capabilities first, and the refused call changes nothing.

compact()

Sends session/compact. It asks the live session’s next compaction check to compact, without a rebuild and without changing any compaction threshold: the check before its next model request compacts. outcome is requested, or already_requested when a request no check consumed yet was already recorded. A check that consumes the request and has nothing to compact (before the session’s first model request, or with nothing to fold) publishes the requested_compaction_skipped event with its reason instead of compaction_started. A session with no live runtime is refused, never woken. mob.compactMember(agentIdentity) does the same for one live mob member, without a respawn.

archive()

Removes this session from the server. The Session object should not be used after calling archive().

invokeSkill()

Known issue, noted 2026-11-13. The four binaries in the Linux x86_64 release archives (rkat, rkat-rpc, rkat-rest, rkat-mcp) start without the built-in skills and report an empty capability list, with no error. The Python and TypeScript SDKs download and start the same rkat-rpc on Linux x86_64, so session.invokeSkill() throws CapabilityUnavailableError there, also for a skill of your own, because it checks the capability report first. A skill of your own that declares requires_capabilities is dropped by those archives without a message. See the known issue on the 0.9.14 release page for the releases and platforms that were checked and for a workaround.
Calls requireCapability("skills"), then runs a turn with the provided structured SkillKey injected. Discover an installed active skill first; names alone need not be unique across sources:
listSkills() returns generated wire-shaped keys; invocation maps key.source_uuid and key.skill_name to sourceUuid and skillName.

send() and peers()

Scope comms operations to this session. Requires the comms capability. Directory entries retain wire-shaped fields, including peer_id and sendable_kinds. Display names are not routing identities and may collide: select the intended sendable peer and send to its peer_id.

subscribeEvents()

Open a standalone event subscription for this session. Returns an async-iterable EventSubscription that yields typed AgentEventEnvelope objects.

Capabilities

Capabilities are fetched automatically during connect(). Use them to guard code paths that depend on optional features.

Config management

getConfig() returns a generated ConfigEnvelope; writes return ConfigWriteResult. These preserve optional nullable snake_case metadata (realm_id, instance_id, backend, resolved_paths, and, for writes, live_propagation). The config field is unknown, not a typed settings object. Patch known fields without spreading it, and print the returned value directly or validate it before reading properties.

Examples


See also