For the full guide, see Comms.
Keep a session alive for inbound work
Keep-alive sessions stay resident so later comms or external events can wake them up as future runtime-backed work.
CLI
JSON-RPC
REST
Python
TypeScript
rkat run --comms-name agent-a --keep-alive "You are a coordinator."
{
"jsonrpc": "2.0",
"id": 1,
"method": "session/create",
"params": {
"prompt": "You are a coordinator.",
"keep_alive": true,
"comms_name": "agent-a"
}
}
curl -X POST http://localhost:8080/sessions \
-H "Content-Type: application/json" \
-d '{
"prompt": "You are a coordinator.",
"keep_alive": true,
"comms_name": "agent-a"
}'
session = await client.create_session(
"You are a coordinator.",
keep_alive=True,
comms_name="agent-a",
)
const session = await client.createSession("You are a coordinator.", {
keepAlive: true,
commsName: "agent-a",
});
Listen as a remote signed peer
Use the rkat run comms flags when the agent process itself should be reachable
by other Meerkats or by a mob supervisor:
rkat run \
--comms-name remote-reviewer \
--comms-listen-tcp 0.0.0.0:4200 \
--comms-advertise-tcp reviewer.example.com:4200 \
--comms-binding-out ./remote-reviewer.binding.json \
--keep-alive \
"You review work sent over signed comms."
rkat-rpc --tcp, which exposes JSON-RPC for hosts and
SDKs rather than the signed peer channel.
Send a typed comms command
comms/send is the typed host-side comms surface. Use it for local input, peer messages, peer lifecycle notifications, peer requests, and peer responses. The to field is the canonical peer ID (from comms/peers), not a display name.
JSON-RPC
REST
MCP
Python
TypeScript
{
"jsonrpc": "2.0",
"id": 2,
"method": "comms/send",
"params": {
"session_id": "01936f8a-...",
"kind": "peer_message",
"to": "0193a1b2-...",
"body": "Build failed in CI. Please investigate.",
"handling_mode": "queue"
}
}
curl -X POST http://localhost:8080/comms/send \
-H "Content-Type: application/json" \
-d '{
"session_id": "01936f8a-...",
"kind": "peer_message",
"to": "0193a1b2-...",
"body": "Build failed in CI. Please investigate.",
"handling_mode": "queue"
}'
{
"name": "meerkat_comms_send",
"arguments": {
"session_id": "01936f8a-...",
"kind": "peer_message",
"to": "0193a1b2-...",
"body": "Build failed in CI. Please investigate.",
"handling_mode": "queue"
}
}
receipt = await session.send(
kind="peer_message",
to="0193a1b2-...",
body="Build failed in CI. Please investigate.",
handling_mode="queue",
)
print(receipt)
const receipt = await session.send({
kind: "peer_message",
to: "0193a1b2-...",
body: "Build failed in CI. Please investigate.",
handling_mode: "queue",
});
console.log(receipt);
List discoverable peers
Use comms/peers to see which trusted peers are currently visible to the session runtime.
JSON-RPC
REST
MCP
Python
TypeScript
{
"jsonrpc": "2.0",
"id": 3,
"method": "comms/peers",
"params": {
"session_id": "01936f8a-..."
}
}
curl "http://localhost:8080/comms/peers?session_id=01936f8a-..."
{
"name": "meerkat_comms_peers",
"arguments": {
"session_id": "01936f8a-..."
}
}
peers = await session.peers()
for peer in peers:
print(peer["name"])
const peers = await session.peers();
peers.forEach((peer) => console.log(peer.name));
Inject a durable external event
Use session/external_event when the event should enter the runtime’s external-ingress lane rather than the comms command lane.
JSON-RPC
REST
Python
TypeScript
{
"jsonrpc": "2.0",
"id": 4,
"method": "session/external_event",
"params": {
"session_id": "01936f8a-...",
"kind": "generic_json",
"event_type": "deploy_complete",
"payload": {
"environment": "prod",
"release": "2026.04.21"
}
}
}
curl -X POST http://localhost:8080/sessions/01936f8a-.../external-events \
-H "Content-Type: application/json" \
-d '{
"kind": "generic_json",
"event_type": "deploy_complete",
"payload": {
"environment": "prod",
"release": "2026.04.21"
}
}'
await session.send_external_event(
"deploy_complete",
{
"environment": "prod",
"release": "2026.04.21",
},
)
await session.sendExternalEvent("deploy_complete", {
environment: "prod",
release: "2026.04.21",
});
Use comms/send for typed inbox and peer communication. Use session/external_event when an outside system is appending durable runtime-backed work.
Next step
