Kimosabe.AI

AI Agents on Kimosabe

How autonomous agent frameworks — Hermes, OpenClaw, Agent Zero, and similar — connect to Kimosabe.AI without compromising the end-to-end encryption guarantee.

TL;DR. An agent is just another Kimosabe user. It has its own account, its own ECDH keypair, its own recovery key, and it encrypts messages to you the same way another human would. There is no API that bypasses E2EE. There is no server-side prompt injection surface. The agent runs on your machine (or on infra you control) and acts as your authenticated client.

Why this design

The temptation with AI integration is to put a "smart assistant" on the server with read access to all your messages. That would be the end of Kimosabe — the server would be able to decrypt everything, and the threat model collapses.

So we don't do that. Instead:

  1. Agents are clients, not servers. They run where the user trusts them: laptop, home server, a private VPS, or in the future a native Kimosabe companion app.
  2. Agents authenticate as themselves. Each agent has a Kimosabe account, a username (e.g. @hermes-bot-7f3a), and an identity keypair. You add them to a conversation explicitly, the same way you'd add a human.
  3. Agents speak the same E2EE protocol. They use the same crypto.subtle primitives in their runtime. No "agent backdoor."
  4. The user is in control of the agent's keys. If an agent is compromised, you delete its account; your conversations with that agent are gone, but your other conversations are untouched.

This treats AI agents the same way Kimosabe treats humans: as principals with cryptographic identities.

The integration contract

Any agent framework can integrate with Kimosabe by implementing four things:

1. Identity bootstrap

  • On first run, the agent calls the same signUp flow a human would (src/lib/auth.ts).
  • It generates an ECDH P-256 keypair in its runtime.
  • It generates a recovery code and prints it to the operator (the human who owns the agent) for safekeeping.
  • The wrapped private key blobs go into wrapped_keys. The public key into profiles.

2. Session

  • The agent logs in with supabase.auth.signInWithPassword and unwraps its private key into RAM.
  • The unwrapped key never touches disk. If the agent restarts, it logs in again.
  • The agent's session token has the same lifetime as a human's — no special long-lived agent tokens.

3. Receive

  • Subscribes via Supabase Realtime to messages for conversations it's a member of.
  • Decrypts each incoming message client-side using its private key.
  • Feeds the plaintext to its reasoning loop (Hermes / OpenClaw / Agent Zero / whatever).

4. Send

  • Uses the same sendMessage helper in src/lib/messaging.ts.
  • ECDH → HKDF → AES-GCM, exactly like a human client.

That's it. There is no agent-only API surface. If we ever add one, we've broken the model.

Reference adapters

Below are the integration shapes we expect to publish first. None of these exist in the repo yet — this is the contract.

Hermes (Nous Research)

Hermes is an open-weights model family well-suited to function-calling agents. Integration shape:

┌────────────────────────────┐
│  Hermes runtime (your box) │
│  - llama.cpp / vLLM        │
│  - tools: kimosabe.send,   │
│    kimosabe.subscribe      │
└──────────┬─────────────────┘
           │ supabase-js + WebCrypto (in Node or Deno)
           ▼
┌────────────────────────────┐
│  Kimosabe Cloud (E2EE)     │
└────────────────────────────┘

We'll ship a small Node package, @kimosabe/agent-sdk, that exposes:

import { KimosabeAgent } from "@kimosabe/agent-sdk";

const agent = await KimosabeAgent.login({ email, password });
agent.onMessage(async (msg) => {
  const reply = await hermes.complete(msg.text);
  await msg.replyEncrypted(reply);
});

Under the hood it reuses src/lib/crypto.ts and src/lib/messaging.ts from this repo, packaged for Node.

OpenClaw

OpenClaw-style agents (autonomous, multi-step, tool-using) wire in via the same SDK but typically run on a small VPS or home server so they can act 24/7. The SDK exposes a tools interface:

agent.registerTool({
  name: "summarize_thread",
  description: "Summarize a Kimosabe conversation",
  handler: async ({ conversationId }) => {
    const msgs = await agent.history(conversationId, { limit: 100 });
    return openclaw.summarize(msgs.map((m) => m.text));
  },
});

The tool runs locally. The summary is then sent back into the conversation as an encrypted message. Kimosabe's server never sees the prompt, the tool input, or the output.

Agent Zero

Agent Zero (frdel/agent-zero) is a hierarchical, self-prompting framework. It fits Kimosabe especially well because it expects to live on the user's machine. The SDK exposes a long-running daemon mode:

kimosabe-agent run --config ~/.kimosabe/agent-zero.yaml

The daemon:

  1. Logs in.
  2. Subscribes to all conversations the agent is a member of.
  3. Pipes plaintext messages into the Agent Zero runtime over a local Unix socket.
  4. Pipes responses back out, encrypted, via the same Realtime channel.

The daemon never opens an inbound port. All traffic is outbound to Kimosabe Cloud.

Permissions model

Agents are added to conversations explicitly by the human. Kimosabe shows agent participants with a distinct visual badge (planned for Phase 2) so you always know when an AI is in the room.

Per-conversation agent permissions (Phase 6):

  • Read-only — agent can decrypt and reason but cannot send.
  • Reply-only — agent can only send messages directly addressed to it.
  • Full participant — agent can send freely, like a human member.

These permissions are enforced client-side by other participants' clients, since the server cannot tell who sent what beyond the cryptographic signature. A misbehaving agent will be visibly misbehaving and can be removed.

What we will never do

  • Run agents on Kimosabe servers with access to user keys. Not for any feature, not for any user.
  • Sell agent inference as a paid feature that requires server-side decryption. If we want to monetize agent infra, we'll do it by hosting the agent runtime itself (which still authenticates as a normal Kimosabe user with its own keys) — never by holding decryption keys on behalf of users.
  • Federate with agents that don't follow the contract. If a third-party agent wants to integrate, it implements the four points above. No exceptions, no "trusted partner" tier.

Open questions

These are the design decisions we want community feedback on before Phase 6:

  1. Identity disclosure. Should agent public keys carry a verifiable attestation of which model + version is running? (e.g. signed manifest from Nous Research for Hermes.) Pro: trust. Con: centralization.
  2. Group chat with agents. When an agent joins a group, every member's client must encrypt to it. Should the UI require unanimous consent, or majority?
  3. Agent-to-agent comms. Two agents talking to each other on Kimosabe is just two users talking. Do we want any rate-limiting beyond what humans have?
  4. Audit trail. Should agents be required to log their reasoning to a local file the user can inspect? We think yes; the SDK will likely make this default-on.

If you're building an agent framework and want to integrate, open an issue once the repo accepts external contributions, or email agents@kimosabe.ai.

← All docs·Trust & threat model