Technical Documentation

Rare Agents Docs

Version 2.0 — March 2026

Executive Summary

Rare Agents is a multi-tenant AI agent platform that enables individuals and businesses to create, configure, and deploy personal AI agents powered by frontier large language models. Built by the Blockchain Development Foundation, Rare Agents has evolved into a comprehensive personal AI ecosystem — moving far beyond single-session chatbots toward persistent, configurable agent workspaces with browser automation, encrypted data storage, service integrations, and a peer-to-peer data marketplace.

Each agent on the platform is an isolated workspace with its own identity (system prompt), model selection, tool configuration, chat history, browser control capability, and Solana wallet integration. The platform wraps this with five major add-on systems: a Personal Data Vault (AES-256-GCM encrypted storage with Solana proof-of-existence), OAuth Connectors (Google, Slack, Notion, GitHub), a Data Marketplace (cryptographic licensing, peer-to-peer data sales), Browser Automation (Chrome extension–based web control driven by AI), and Messaging Channels (WhatsApp via Baileys QR and Telegram via per-user bot tokens — enabling agents to respond to messages on mobile devices in real time).

The platform is live, production-ready, and accessible at rareagents.ai. This whitepaper covers the complete technical architecture, data systems, security model, and business structure underlying the platform as of version 2.0.

Introduction

The emergence of large language models has created a new software category: AI agents. Unlike traditional chatbots that respond to single queries, agents maintain context, follow instructions defined in a system prompt, use tools, remember past interactions, and can interact with external systems. The challenge has been making this capability genuinely accessible — deploying even a basic agent today requires API keys, infrastructure, prompt engineering skill, and significant time.

Rare Agents solves this by wrapping the full agent lifecycle into an intuitive dashboard. Users go from signing up to running a custom AI agent in under two minutes. No API keys, no infrastructure, no code required. And with the V2 platform, agents can now browse the web on the user's behalf, store and encrypt what they learn, connect to the services users already use, and participate in a marketplace where that data has real value.

Founder

Mario Butler brings over 18 years of business leadership, a Master's degree in Business, and deep expertise in blockchain technology — including smart contract auditing experience with Quantstamp and a Dragonchain-certified Smart Contract Practitioner credential. He has been an active investor in private AI infrastructure projects for over 7 years. His previous ventures include Dreamster (a crypto ecosystem for the music industry) and Progressive Counseling (7 CARF accreditations, most recently valid through February 2029). Rare Agents is his vision for democratizing AI agent technology while returning data ownership to the individual.

Mission

To make personal AI agents as accessible and powerful as email — giving every person and business a configurable AI teammate that works for them, remembers them, protects their data with encryption, and empowers them to profit from what their agents create.

Problem Statement

Current AI products fall into two camps. Consumer chat products (ChatGPT, Claude, Gemini) are excellent at single-turn interactions but have limited configurability. Developer platforms (OpenAI API, Anthropic API) offer full control but require engineering expertise and significant overhead for non-technical users.

Beyond the agent gap, there is a structural data problem. Every AI platform in existence today treats user data as a platform asset — it's used to train models, improve services, and generate revenue for the platform operator. Users have no visibility into how their data is used, no tool to protect it, and no mechanism to profit from it themselves.

Key pain points Rare Agents addresses:

  • ✕No persistence — every chat session starts from scratch
  • ✕No specialization — can't give the AI a persistent identity without technical setup
  • ✕No tool control — can't choose which capabilities the agent has access to
  • ✕No web automation — no consumer AI product can control your browser
  • ✕No data protection — generated data is stored in plaintext on third-party servers
  • ✕No connectors — no way to bring your Gmail, Slack, or GitHub into your AI workspace
  • ✕No monetization — users generate valuable data and see zero return
  • ✕No blockchain integration — no consumer AI agent has first-class Solana support
  • ✕No audit trail — no way to review everything your AI did on your behalf

Product Overview

Rare Agents is a web application accessible at rareagents.ai. It presents a professional dark-themed dashboard with a left sidebar navigation and agent-centric workspace layout, intentionally designed to feel like an enterprise control panel.

Dashboard sections

  • DashboardOverview of agents, activity, token usage, and plan status
  • AgentsCreate and manage AI agents — each a persistent isolated workspace
  • Agent DetailSeven-tab workspace: Chat, Browser, Tools, Solana, Memory, Logs, Settings
  • Data VaultAES-256-GCM encrypted personal data storage with Solana proofs
  • ConnectorsOAuth connections to Google, Slack, Notion, and GitHub
  • MarketplaceBrowse, list, purchase, and license encrypted datasets
  • BillingPlan management, token usage, and subscription upgrade
  • ActivityFull platform audit log with filters
  • SettingsProfile and account management

Agent workspace tabs

  • ChatReal-time streaming conversation with the agent using its identity and configured tool set
  • BrowserConnect Chrome extension, send manual commands, or run AI-driven agentic browser tasks
  • ToolsToggle web search, document analysis, Solana memo, and SOL transfer on/off per agent
  • SolanaConnect a Solana wallet, send memos, build and preview SOL transfers
  • MemoryEdit the agent's system prompt (identity) and behavioral instructions
  • LogsAgent-scoped audit log of all actions and events
  • SettingsRename, change model, toggle status, or delete the agent

AI Architecture

All AI inference is powered by a decentralized serverless AI network — a privacy-preserving compute layer that routes requests to the world's leading open-weight large language models via an OpenAI-compatible endpoint. All supported models run inside Trusted Execution Environments (TEE), ensuring user prompts and responses are never exposed to the host infrastructure.

Supported models

DeepSeek V3.2

TEE · Recommended

Newest DeepSeek iteration. Cutting-edge reasoning quality and speed.

DeepSeek V3.1

TEE · Stable

Balanced option. Proven and battle-tested across production workloads.

Qwen 2.5 72B

Multilingual

Strong on research, writing, and multilingual tasks.

Qwen3 235B

TEE · Deep Reasoning

Largest model. Complex multi-step reasoning and analysis.

Streaming architecture

Rare Agents uses Server-Sent Events (SSE) for real-time token streaming. When a user sends a message, the backend forwards the request to our decentralized inference layer and streams each token directly to the browser — producing the typewriter effect visible in the chat interface. SSE requires no WebSocket connection management overhead and works reliably across proxies and cloud environments.

Token counting

The platform uses tiktoken (OpenAI's tokenizer library) to estimate token consumption for every prompt and completion. Token usage is stored in the database against each user account and agent, enabling accurate billing enforcement across all subscription tiers.

Agent Model

Each agent is a persistent database record with associated messages, tools, browser sessions, and configuration. Agents are fully isolated per user — there is no shared state between users or between agents within the same account.

Agent data model

Agent {

id: integer (primary key)

userId: text (owner)

name: text

description: text

systemPrompt: text (agent identity — Memory tab)

soulDocument: jsonb (Soul Builder identity layer — Identity tab)

model: text (LLM selection)

status: "active" | "stopped"

avatarColor: text

dataCollectionMode: "off" | "minimal" | "full"

monetizationEnabled: boolean

allowedConnectors: string[]

createdAt / updatedAt: timestamp

}

System prompt (identity)

The system prompt defines the agent's persona, tone, expertise, and operating rules. The platform provides starter templates (Personal Assistant, Web Automation Agent, Solana Ops Agent, Research Agent) or users can write custom identities. The identity is editable at any time from the Memory tab and is automatically enriched with browser automation instructions when relevant.

Soul Document (deep identity layer)

The Soul Document is a structured JSONB field that encodes the agent's deeper identity — character traits, core values, trust level (Open / Guarded / Selective / Confidential), and identity stability (Fluid / Adaptive / Stable / Immutable). It is composed using the Soul Builder interface in the agent's Identity tab and compiled into a system prompt layer injected between Domain Intelligence (L2.5) and the user's custom system prompt (L3) at inference time. Four starter templates are available: Sage Advisor, Loyal Companion, Strategic Operator, and Creative Visionary. Unlike the system prompt, the Soul Document is not presented to the model as editable instructions — it is rendered as a fixed identity constitution.

Message history

Agent messages are stored in the agent_messages table (role: user | assistant | system, content, tokenCount, timestamp). The full message history is included in every subsequent API call, enabling true persistent memory across sessions.

Tools & Capabilities

Rare Agents implements a per-agent tool registry. Each agent has individually configurable tool access stored in the agent_tools table. Tools can be enabled/disabled and flagged as requiring explicit user approval before execution.

Web Searchweb_search

Queries DuckDuckGo's API for real-time search results. Results are injected into the conversation context, allowing the agent to answer with up-to-date information. No API key required. Enabled by default.

Libraries: duck-duck-scrape

Document Analysisdocument_analysis

Accepts file uploads (PDF, DOCX, XLSX, PPTX) via the chat interface. The server extracts text using format-specific parsers and injects the content into the conversation. Max 10MB per file, 5 files per request.

Libraries: pdf-parse, mammoth, xlsx, officeparser

Solana Memosolana_memo

Builds a Solana Memo Program instruction from user-provided text. Returns a transaction preview object to the client. Requires explicit user approval before any signing occurs. Disabled by default.

Libraries: @solana/web3.js

SOL Transfersolana_transfer

Builds a SOL transfer instruction (lamports = SOL × 1,000,000,000). Returns a preview with recipient, amount, and estimated fee. Requires explicit approval. Pro and Elite plans only. Disabled by default.

Libraries: @solana/web3.js

Browser Automation

Rare Agents implements a full browser control system using a Chrome extension (Manifest V3) connected to the platform via WebSocket. This allows any agent to navigate, interact with, and read content from any website the user is logged into — making Rare Agents one of the only consumer AI platforms with true browser-level automation.

Architecture

Chrome Extension (Manifest V3) — runs in user's browser

↓ WebSocket connection to /ws/browser?token=<jwt>&agentId=<id>

Backend WS handler (server/browser-ws.ts) — manages sessions

↓ Receives commands from server, executes in browser, returns results

Browser Agent (server/browser-agent.ts) — AI-driven agentic loop

↓ Takes goal → generates step-by-step plan → executes via WS → observes → continues

Browser Routes (server/browser-routes.ts) — REST API for tab UI

Manual commands

The Browser tab in the agent workspace exposes manual command controls: navigate (go to URL), click (CSS selector), type (selector + text), screenshot (capture current view), and scroll (direction + amount). These can be sent individually for testing or debugging without running a full agentic task.

Agentic task mode

Users can describe a high-level goal in natural language (e.g., "post my research summary to LinkedIn and share it in the #general Slack channel"). The backend's agentic loop calls the LLM to generate a plan, executes each step via the WebSocket, receives screenshots or DOM data as feedback, and continues until the task is complete or the user interrupts. Results stream to the browser via SSE.

Extension distribution

The Chrome extension source lives in the extension/ folder of the platform. Users download it as a ZIP via GET /api/extension/download and load it unpacked in Chrome's developer mode. Future distribution via the Chrome Web Store is planned for V3.

Security model

The WebSocket endpoint requires a valid JWT token and a valid agent ID owned by the authenticated user. All commands are logged to the audit trail. The extension only connects to the domain it was configured for — it cannot be used to connect to a different user's platform instance.

Messaging Channels

The Messaging Channels system extends each agent's reach beyond the browser dashboard into the messaging applications users already rely on daily. Rather than requiring users to visit a web interface, agents can respond to messages sent directly via WhatsApp or Telegram — making AI assistants available wherever the user happens to be.

Each integration is per-user and per-agent. A user's WhatsApp session or Telegram bot token is associated specifically with one agent. There are no platform-level phone numbers or shared bots — every connection is independent and private.

WhatsApp via Baileys

WhatsApp integration is implemented using @whiskeysockets/baileys — an open-source Node.js library that replicates the WhatsApp Web multi-device protocol. This approach requires no Meta developer account, no official WhatsApp Business API subscription, and no per-message fees. The user links their personal or business WhatsApp account by scanning a QR code through the Channels tab — the same experience as WhatsApp Web.

1. User clicks 'Connect WhatsApp' in agent's Channels tab

2. Server initializes a Baileys session, generates QR code

3. GET /api/agents/:id/channels/whatsapp/qr — returns base64 QR image

4. User scans QR with their phone (exactly like WhatsApp Web)

5. Baileys session is established; auth state saved to DB (sessionData JSONB)

6. Session is auto-restored from DB on server restart

7. Incoming messages → AI processes → response sent back to WhatsApp

Telegram via per-user bot tokens

Telegram integration uses the official Bot API with a per-user bot token model. Each user creates their own Telegram bot via @BotFather and pastes the bot token into the Channels tab. The platform validates the token, stores it (encrypted) as accessToken in the messaging_integrations table, and registers a webhook at /api/webhooks/telegram/:integrationId.

Webhooks are verified using a X-Telegram-Bot-Api-Secret-Token header. The server generates a random secret per integration and passes it during webhook registration — any incoming webhook request without this header is rejected. This ensures that only legitimate Telegram-originated requests are processed.

Message processing pipeline

Incoming message received (WhatsApp event or Telegram webhook POST)

Integration record fetched → agent ID identified

Last 20 agent_messages fetched for conversation context

AI request built: system prompt + message history + new message

Decentralized AI inference call (streaming collected to completion)

Response message stored in agent_messages

Response sent back to user via WhatsApp or Telegram API

Data model

MessagingIntegration {

id: uuid

agentId: uuid

userId: integer

platform: "whatsapp" | "telegram"

accessToken: text (Telegram bot token)

verifyToken: text (Telegram webhook secret)

botUsername: text

sessionData: jsonb (Baileys WhatsApp auth state)

externalId: text (Telegram chat ID)

linked: boolean

linkedAt: timestamp

}

API endpoints

  • GET /api/agents/:id/channels — list all channel connections for agent
  • POST /api/agents/:id/channels/whatsapp/connect — initialize Baileys session
  • GET /api/agents/:id/channels/whatsapp/qr — get QR code image (base64)
  • POST /api/agents/:id/channels/telegram/connect — register Telegram bot
  • DELETE /api/agents/:id/channels/:platform — disconnect and remove session
  • POST /api/webhooks/telegram/:integrationId — Telegram webhook receiver

Security considerations

WhatsApp session credentials (Baileys auth state) are stored encrypted in the sessionData JSONB column. Telegram bot tokens are stored as accessToken. Neither is ever returned to client-side JavaScript. Webhook requests from Telegram are verified by header token comparison using crypto.timingSafeEqual to prevent timing attacks. No platform-level credentials are required — each user's integration is fully isolated.

Upcoming channels

WeChat and SMS are displayed as "Coming Soon" in the Channels UI. WeChat integration will use the WeChat Work API for business accounts. SMS will use a configurable provider (Twilio or Vonage) with a per-user phone number. Both are planned for V3.

Intelligence Vault (Personal Data Vault)

The Intelligence Vault is an encrypted private data store where users can save any information their agents collect, generate, or synthesize. Unlike plaintext database storage, every vault item is encrypted before storage using a key derived from the user's identity — meaning even a full database compromise would not expose vault contents in readable form. Beyond raw storage, the Intelligence Vault runs every saved item through an AI asset extraction pipeline that classifies content, extracts structured signals, scores data quality, and detects PII — turning raw encrypted blobs into actionable intelligence assets.

AI Asset Extraction Pipeline

Every vault save triggers an asynchronous LLM pipeline (DeepSeek-V3 via Chutes AI) that performs the following steps:

1. Classify content into 1–3 of 12 business intelligence categories

Categories: Purchase Intent, Financial Behavior, Market Intelligence, Consumer Sentiment,

Competitive Intelligence, Behavioral Patterns, Professional Networks, Technology Adoption,

Geographic Insights, Health & Wellness, Lifestyle & Interests, Regulatory & Compliance

2. Extract structured intelligence signals (key named findings from the content)

3. Score: value (0–100), confidence (0–100), completeness (0–100)

4. Detect PII presence (boolean flag)

5. Write a data_assets record linked to the vault item

Data Assets & Permissions

The vault UI is a 3-tab dashboard: My Assets (categorized asset cards with value scores and signal previews), Data Permissions (per-category consent controls for collection and monetization), and Vault Storage (raw encrypted item list). The data_permissions table stores per-user, per-category consent flags — allowing users to block specific categories from being collected or listed on the marketplace.

Data Asset model

DataAsset {

id: uuid

userId: integer

vaultItemId: uuid (FK → vault_items)

category: text (one of 12 business categories)

signals: string[] (extracted intelligence signals)

valueScore: integer (0–100)

confidenceScore: integer (0–100)

completenessScore: integer (0–100)

hasPii: boolean

createdAt: timestamp

}

Encryption implementation

Algorithm: AES-256-GCM (authenticated encryption)

Key derivation: scrypt(userId + ENCRYPTION_MASTER_KEY, salt, N=16384, r=8, p=1)

Key length: 32 bytes (256 bits)

IV: 16 bytes random per item

Auth tag: 16 bytes (GCM integrity check)

Storage format: iv:authTag:ciphertext (hex encoded)

Content integrity

Every vault item receives a SHA-256 content hash computed from the plaintext before encryption. This hash is stored alongside the encrypted content. Users can verify the integrity of any item at any time by comparing the current hash against the stored hash — detecting any tampering even if the encryption is somehow bypassed.

Solana proof-of-existence

Each vault item is recorded in the solana_ledger_records table with the SHA-256 content hash, a timestamp, and a Solana transaction signature. This creates an immutable timestamped proof that the data existed at a specific point in time — useful for demonstrating data provenance in marketplace transactions.

Vault data model

VaultItem {

id: uuid

userId: integer

title: text

encryptedContent: text (iv:authTag:ciphertext)

contentHash: text (SHA-256)

dataType: text

tags: string[]

sizeBytes: integer

solanaProofStatus: "mocked" | "confirmed"

createdAt / updatedAt: timestamp

}

API endpoints

Vault operations are exposed via a RESTful API protected by JWT authentication:

  • GET /api/vault — list all vault items (metadata, no plaintext)
  • POST /api/vault — create new encrypted item
  • GET /api/vault/:id — fetch and decrypt a single item
  • PUT /api/vault/:id — update item content (re-encrypts)
  • DELETE /api/vault/:id — permanently delete item
  • GET /api/vault/:id/proof — fetch Solana proof record
  • GET /api/vault/stats/summary — count, size, type breakdown
  • GET /api/consent — list data collection consent scopes
  • POST /api/consent — update consent preferences

OAuth Connectors

The Connectors system allows users to link their most-used external platforms and grant their agents access to the data within them. When OAuth credentials are configured, the platform performs a real OAuth 2.0 authorization code flow. When not configured, it falls back to a mock-connect mode with representative demo data — allowing the full feature set to be demonstrated without requiring production credentials.

Supported platforms

Google (Gmail + Drive)

Gmail read, Drive files list and read

GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET

Slack

Channels list, message history, user list

SLACK_CLIENT_ID, SLACK_CLIENT_SECRET

Notion

Pages and database blocks read

NOTION_CLIENT_ID, NOTION_CLIENT_SECRET

GitHub

Repos, issues, pull requests, commits

GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET

Connection flow

1. User clicks 'Connect' on the provider card

2. GET /api/connectors/:provider/auth — returns OAuth redirect URL

3. User completes OAuth consent in provider's window

4. Callback returns auth code → server exchanges for access token

5. Token stored in oauth_connections table (encrypted at rest)

6. POST /api/connectors/:provider/sync — pulls data using token

7. Synced data returned to UI; can be saved to Data Vault

API endpoints

  • GET /api/connectors — list all connections and their status
  • GET /api/connectors/:provider/auth — get OAuth redirect URL
  • POST /api/connectors/:provider/mock-connect — demo connect
  • DELETE /api/connectors/:provider — disconnect and revoke token
  • POST /api/connectors/:provider/sync — pull latest data

Data Marketplace & Asset Bundles

The Data Exchange enables users to monetize the intelligence assets their agents collect and store in the vault. Sellers create individual listings backed by Intelligence Assets or group multiple assets into premium bundles — themed packages with a single price and a combined value score. Buyers browse with category, data type, price range, anonymization, and minimum value score filters. Payment is processed through Stripe Checkout; enterprise quote listings bypass the checkout flow. After purchase, buyers receive a cryptographic license key and can download the dataset directly from the platform.

Individual listing lifecycle

1. Seller creates a listing (title, description, price, license terms, dataset type)

2. Seller links Intelligence Assets to the listing as the dataset backing

3. Listing cards display enriched data: value score, signal count, anonymization status

4. Seller publishes — listing becomes visible to all platform users

5. Buyer browses marketplace with filters (category, type, price, anonymized, min score)

6. Buyer purchases — POST /api/marketplace/:id/checkout creates a Stripe Checkout Session

7. Buyer completes Stripe payment, returns to platform

8. POST /api/marketplace/:id/complete-purchase finalises the transaction

9. Platform generates a cryptographic license key for the buyer

10. License stored in licenses table with status='active'

11. Seller receives a sales notification; can revoke any license at any time

Asset Bundles

Users can create asset bundles — themed packages of 2 or more related Intelligence Assets listed as a single premium product. Bundle value scores are computed as the weighted average of constituent asset scores. Bundles appear in the Data Exchange browse tab as "Premium Bundles" with a distinct purple card style above individual listings. Buyers receive access to all assets in the bundle under a single license key. Sellers can add or remove individual assets from an existing bundle after creation.

DataBundle { id, userId, title, description, price, licenseType, status, valueScore, createdAt }

BundleAsset { id, bundleId, dataAssetId }

License key generation

License keys are generated using Node.js crypto.randomBytes(32).toString('hex') — a 256-bit cryptographically secure random value. Keys are stored in the licenses table and returned to buyers only once at purchase time. The Solana proof-of-existence record from the vault provides on-chain evidence of data provenance for buyers.

Data model

MarketplaceListing { id, sellerId, title, description, price, datasetType, licenseTerms, status, createdAt }

ListingItem { id, listingId, vaultItemId }

Purchase { id, listingId, buyerId, amount, paymentMethod, purchasedAt }

License { id, purchaseId, licenseKey, status('active'|'revoked'), issuedAt, revokedAt }

API endpoints

  • GET /api/marketplace — browse all published listings
  • GET /api/marketplace/my-listings — seller's own listings
  • GET /api/marketplace/my-purchases — buyer's purchase history
  • POST /api/marketplace — create a new listing
  • POST /api/marketplace/:id/publish — make listing public
  • POST /api/marketplace/:id/purchase — buy a listing
  • POST /api/marketplace/licenses/:id/revoke — revoke a license

Solana Integration

What is Solana? (plain-English overview)

A blockchain is a distributed ledger — a shared record book replicated across thousands of independent computers simultaneously. Any entry written to this ledger is cryptographically linked to all prior entries and verified by network consensus, making retroactive modification computationally infeasible. The result is a public, append-only, tamper-evident log.

Solana is a high-performance Layer-1 blockchain using a Proof of History consensus mechanism alongside Proof of Stake. This combination enables ~50,000 transactions per second with average confirmation times under 400ms and transaction fees typically below $0.001. For Rare Agents' use cases — data provenance timestamps and on-chain memos — these properties make Solana an ideal choice: fast enough to be instant from a user perspective, cheap enough to be used for every vault item, and decentralized enough to provide genuine tamper-proof guarantees.

In practical terms for users: when Rare Agents writes something to Solana, it means that piece of data is now part of a permanent, public, immutable record that no person or company — including Rare Agents itself — can alter or delete.

Rare Agents provides first-class Solana blockchain integration throughout the platform. This spans three distinct layers: the agent Solana tab (wallet, memo, transfer), the vault's proof-of-existence ledger (content hashing + on-chain record), and the marketplace's provenance verification (buyers can verify dataset origin on-chain).

The core principle across all three: the agent proposes, the user disposes. No transaction is ever submitted to the network without explicit user approval.

Wallet connection model

Users enter their Solana wallet public key (base58 encoded) and select a network (devnet by default, mainnet-beta for real operations). The wallet record is scoped to the user's account ID. The platform never requests or stores private keys or seed phrases.

Transaction preview flow

1. User provides intent (memo text or transfer details)

2. POST /api/wallet/memo or /api/wallet/transfer

3. Server builds transaction instruction (no signing occurs)

4. Server returns preview object to client

5. Client renders full preview modal (type, params, fee estimate)

6. User clicks Approve or Cancel

7. On approve: POST /api/wallet/confirm records signature + details

8. Audit log updated with confirmed status

Security & Privacy

Authentication

Authentication uses a custom email + password system with bcryptjs password hashing and jsonwebtoken (JWT) for session tokens. Tokens are signed with a SESSION_SECRET environment variable, expire after 30 days, and are stored in localStorage. Every protected API endpoint verifies the token via requireAuth middleware before processing any request.

Two-factor authentication (TOTP)

Users can optionally enable TOTP-based two-factor authentication from Settings → Security. The implementation uses speakeasy for TOTP code generation and verification (RFC 6238, 30-second windows, SHA-1, 6-digit codes). Setup flow: the server generates a secret and returns a QR code URI; the user scans it with Google Authenticator or Authy; the user confirms with a live 6-digit code; on success, the twoFactorEnabled flag is set and the secret is stored in the user_accounts table.

Two-factor login flow

1. User submits email + password — credentials verified normally

2. If 2FA enabled: server returns { requiresTwoFactor: true, tempToken }

3. tempToken is a short-lived JWT (10-minute expiry) encoding only the user ID

4. Client shows inline 2FA challenge — user enters 6-digit TOTP code

5. POST /api/auth/2fa/verify with { tempToken, code }

6. Server verifies TOTP code against stored secret (accepts ±1 window)

7. If valid: full 30-day JWT issued — login complete

8. If invalid: 401 returned — no JWT issued

Backup codes

On 2FA activation, 8 one-time backup codes are generated using crypto.randomBytes and stored as bcrypt hashes (not plaintext). Each backup code can be used exactly once in place of the TOTP code — consuming it marks it as used in the database. Users can regenerate all 8 codes at any time from the Security settings panel. Disabling 2FA requires confirmation with a live TOTP code or an unused backup code.

2FA API endpoints

  • GET /api/auth/2fa/status — check if 2FA is enabled
  • POST /api/auth/2fa/setup/totp — generate secret + QR code
  • POST /api/auth/2fa/enable — confirm setup with 6-digit code
  • POST /api/auth/2fa/verify — complete 2FA login (tempToken + code)
  • POST /api/auth/2fa/disable — disable 2FA (requires TOTP confirmation)
  • POST /api/auth/2fa/backup-codes/regenerate — regenerate backup codes

Data isolation

Every API endpoint that accesses agent data, messages, tools, wallet connections, vault items, connectors, marketplace listings, or audit logs enforces user ID scoping at the database query level. It is architecturally impossible to access another user's data through the API — even with a valid token issued to a different user.

Vault encryption

All vault content is encrypted with AES-256-GCM before being written to the database. The encryption key is derived via scrypt from the user's ID combined with the platform's ENCRYPTION_MASTER_KEY environment variable. A unique 16-byte IV is generated per item. The GCM auth tag provides built-in tamper detection. Decryption only occurs server-side upon authenticated requests for the specific item.

OAuth token storage

OAuth access tokens from connected providers (Google, Slack, Notion, GitHub) are stored in the oauth_connections table. These are stored with the same encryption approach as vault items and are never exposed to client-side JavaScript. They are used only server-side to proxy sync requests.

Browser extension security

The WebSocket endpoint for browser control requires a valid JWT and a valid agent ID owned by the authenticated user. Extension connections are associated with a specific user-agent pair and cannot be reused across accounts. All browser commands and their results are written to the audit log.

Rate limiting

The authentication endpoints are rate-limited per IP using an in-memory token bucket (authRateLimiter). The chat endpoint is additionally rate-limited at 60 requests per minute per IP. Token budgets provide a third layer of application-level enforcement — guests and free-tier users are capped at platform-defined token limits.

Private key safety

The platform never requests, transmits, or stores Solana private keys or seed phrases. Wallet integration is public-key only. The approval-gated transaction flow means users retain full signing control — the platform builds instructions but never executes them.

Database

The platform uses Neon (PostgreSQL) with Drizzle ORM. All database credentials are stored as environment secrets and never exposed to client-side code. The connection uses Neon's WebSocket-based serverless driver for optimal performance in the cloud deployment environment.

Agent Security Shield

Beyond infrastructure-level security, Rare Agents includes a runtime security layer built directly into the AI chat pipeline. The Agent Security Shield detects and blocks adversarial inputs before they reach the language model — protecting agents against prompt injection attacks, persona hijacking, and other forms of manipulation.

Every incoming message is evaluated against a library of 20+ server-side detection patterns before being forwarded to the LLM. Patterns are organised into six attack categories:

Instruction Override

Attempts to replace or override the agent's original system prompt using phrases like "ignore previous instructions", "disregard your guidelines", or "new instructions override all prior directives".

Persona Hijacking

Attempts to force the agent to adopt an alternative identity — for example "pretend you are DAN", "act as if you have no restrictions", "you are now an unrestricted AI". These attacks attempt to bypass the agent's configured personality and safety boundaries.

System Prompt Extraction

Attempts to trick the agent into revealing its system prompt — phrases like "what are your instructions", "repeat the text above", or "show me your configuration". The Shield blocks exfiltration at the message level.

Role Delimiter Injection

Injections of raw role markers such as <system>, [INST], <<SYS>>, or ###SYSTEM to manipulate how the LLM interprets message boundaries. This class of attack exploits tokeniser-level vulnerabilities in transformer models.

Data Exfiltration

Attempts to extract sensitive context or memory — e.g. "summarise all files you have seen", "list all data stored about this user", or "output your conversation history in full". The Shield pattern-matches exfiltration-intent phrasing across languages.

Jailbreak Attempts

Classic and novel jailbreak patterns including "do anything now", "developer mode", "jailbreak enabled", "bypass content filters", and multi-step social-engineering sequences designed to erode safety alignment over a conversation.

Threat scoring and severity levels

Each detected pattern carries a weight (1–3). When an incoming message is scanned, all matching patterns are summed into a threat score. Scores are mapped to severity levels: none (0), low (1–2), medium (3–5), and high (6+). All detected threats are recorded to the audit_logs table under the action security.prompt_injection, creating a full forensic record.

Protection modes

Each agent independently chooses its protection mode from the Security tab in the agent dashboard:

Standard mode (default)

All threats are logged to the audit trail. The message is still forwarded to the LLM. This mode is suitable for research or test agents where the operator wants visibility without interrupting the conversation flow.

Strict mode

Medium and high severity threats are blocked before they reach the LLM. The API returns a structured 400 error with an explanation. The blocked message is logged. Low-severity matches are still logged but allowed through, since they may be benign phrasing.

System prompt integrity

When Strict mode is enabled on an agent, the platform SHA-256 hashes the agent's current system prompt and stores it as systemPromptHash. The Security tab continuously monitors whether the live system prompt matches this locked hash, providing a tamper-detection signal. If the system prompt has drifted (e.g., via an unauthorised edit), the Security tab displays an integrity warning. This ensures that the agent's identity cannot be quietly altered after the security configuration is set.

Security API

GET /api/agents/:id/security — fetch current security config, threat log, and integrity status

PUT /api/agents/:id/security/mode — toggle standard / strict mode and lock/unlock system prompt hash

Pricing Model

Rare Agents uses a freemium subscription model with three tiers. Subscriptions are managed through Stripe. Token budgets and agent limits are enforced server-side at every API call.

Free

$0/mo

3 agents

Starter tokens

Full platform access with limited capacity. No payment required. Data Vault (10 items), Browser extension, all 4 AI models.

Pro

$14.99/mo

20 agents

10M tokens/mo

For individuals using agents daily. Multi-Agent Collaboration, full vault access, all 4 OAuth connectors, marketplace listings, SOL transfers.

Elite

$24.99/mo

Unlimited agents

100M tokens/mo

For teams and power users. Unlimited vault items, all tools, unlimited marketplace listings, priority support.

Marketplace revenue model

The Data Marketplace creates a secondary revenue model beyond subscriptions. When a user sells a dataset, the transaction flows through the platform. Future versions will introduce a platform fee on marketplace transactions; the V2 marketplace uses mock payment processing to demonstrate the full purchase and licensing lifecycle.

Roadmap

V2 — Current (March 2026)

Live
  • Multi-tenant agent dashboard with 7-tab agent workspace
  • 4 AI models via decentralized TEE infrastructure (DeepSeek V3.2, DeepSeek V3.1, Qwen 2.5 72B, Qwen3 235B)
  • Web search + document analysis tools
  • Solana memo + SOL transfer (approval-gated)
  • Browser Automation (Chrome extension + WebSocket + agentic task loop)
  • Messaging Channels: WhatsApp (Baileys QR) + Telegram (per-user bot token)
  • Personal Data Vault (AES-256-GCM encryption, SHA-256 hashing, Solana proofs)
  • OAuth Connectors (Google, Slack, Notion, GitHub)
  • Data Marketplace (listings, purchases, cryptographic license keys, revocation)
  • TOTP two-factor authentication with backup codes
  • Freemium subscription model (Free / Pro / Elite)
  • Full audit logging + activity dashboard
  • Custom JWT authentication (email + password)

V3 — Q3 2026

Planned
  • Agent scheduling (run tasks on a timer)
  • Custom tool builder (bring your own API endpoint)
  • Team workspaces + shared agents
  • Webhook integrations (Slack, Discord, Telegram notifications)
  • Persistent vector memory per agent (long-term recall)
  • Chrome Web Store extension distribution
  • Real Stripe payment processing for marketplace transactions
  • Platform fee model on marketplace sales
  • Agent marketplace (share and install agent templates)

V4 — Q1 2027

Research
  • Multi-agent workflows (agents that coordinate and delegate)
  • Full Solana wallet signing in-browser (Phantom / Solflare adapter)
  • RAAI token integration for premium tool access and marketplace fees
  • On-chain agent identity (Solana NFT per agent)
  • Mobile app (iOS + Android)
  • Agent analytics dashboard (performance, task completion, token trends)
  • Real-time data connector sync (webhook-based, not manual)

Try the platform today

No credit card. No setup. Free tier available to explore every feature.

Launch Dashboard