@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
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
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()
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-ingenerate_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.
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.
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 runsMEERKAT_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()
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()
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()
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:turn()
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.
stream()
EventStream, whose iterator is typed as
AsyncIterable<StreamEvent>. The session’s last-result shortcuts are updated
when iteration completes.
transientTurnContext carries request-only host facts and is not a
transcript message.
interrupt()
turn/interrupt for this session. Has no effect if no turn is running.
stopRun()
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.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()
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()
Session object should not be used after calling archive().
invokeSkill()
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()
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()
EventSubscription that yields typed AgentEventEnvelope objects.
Capabilities
Capabilities are fetched automatically duringconnect(). Use them to guard code paths that depend on optional features.
Known capability IDs
Known capability IDs
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
Structured output
Structured output
Multi-turn conversation
Multi-turn conversation
Streaming a turn
Streaming a turn
Invoking a skill
Invoking a skill
Multimodal prompt (image input)
Multimodal prompt (image input)
Using collectText() for simple streaming
Using collectText() for simple streaming
See also
- TypeScript SDK reference - types, events, errors, and version compatibility
- Rust SDK overview - Rust library API
- RPC reference - JSON-RPC protocol specification
