Skip to content
Hivekeep Hivekeep Docs
Back to site

Mini-Apps Overview

Mini-apps are small web applications that Agents create and manage. They appear in the Hivekeep sidebar and can be opened as side panels or full pages, giving Agents the ability to build interactive UIs on the fly.

What Are Mini-Apps?

Section titled “What Are Mini-Apps?”

A mini-app is a self-contained web application (HTML + JSX + CSS) stored in Hivekeep’s database and served through its built-in web server. Agents create them using AI tools, no manual coding required.

Key features:

  • React-based with server-side JSX transpilation (no build step)
  • Component library with 50+ themed components
  • Persistent storage via key-value API
  • Backend support with server-side JavaScript (_server.js)
  • Background services: backends can declare "background": true to run at boot with lifecycle hooks (onStart/onStop), scheduled cron jobs, and managed timers
  • Real-time events via SSE between backend and frontend, bidirectional (the UI can send events to the backend) and targetable per user
  • Platform notifications from the backend (notification center + external channels)
  • Capability permissions: user-approved access to vault secrets, LLM completions, the maintainer Agent (messages and sub-tasks), and messaging channels
  • Platform API: build UI extensions that manage Hivekeep’s own resources (contacts, crons, projects…) through the same REST API the settings pages use, gated per resource
  • Event-reactive: a background backend can subscribe to platform events (ctx.on("task:done" | "channel:message-received" | "contact:created"…)) and act the moment something happens, gated per event family
  • Theme-aware with automatic light/dark mode support
  • Snapshots for versioning and rollback

How It Works

Section titled “How It Works”
User asks Agent → Agent calls create_mini_app → App appears in sidebar
                Agent writes files          → App auto-reloads
                Agent updates storage       → App reflects changes

Agents have full control over mini-apps through built-in tools:

ToolDescription
create_mini_appCreate a new app (HTML or template)
update_mini_appUpdate metadata (name, icon, description)
delete_mini_appRemove an app permanently
list_mini_appsList all apps for the current Agent
write_mini_app_fileWrite or update any file in an app
read_mini_app_fileRead a file’s content
delete_mini_app_fileRemove a file
list_mini_app_filesList all files with sizes
get/set/delete/list/clear_mini_app_storageManage key-value storage
create/list_mini_app_snapshotCreate versioned backups
rollback_mini_appRestore a previous version

Architecture

Section titled “Architecture”
┌─────────────────────────────────┐
│  Hivekeep UI (sidebar / panel)    │
│  ┌───────────────────────────┐  │
│  │  Mini-App (iframe)        │  │
│  │  • React + JSX            │  │
│  │  • @hivekeep/react hooks    │  │
│  │  • @hivekeep/components     │  │
│  └───────┬───────────────────┘  │
│          │ postMessage SDK      │
├──────────┼──────────────────────┤
│  Hivekeep Server                  │
│  • JSX transpiler               │
│  • Static file server           │
│  • Storage API                  │
│  • Backend runtime (Hono)       │
│  • SSE events                   │
└─────────────────────────────────┘

Mini-apps run in an iframe and communicate with Hivekeep through a postMessage-based SDK. The SDK provides hooks for React, a component library, storage, theming, and more.

Quick Example

Section titled “Quick Example”

An Agent can create a simple counter app:

// Created via create_mini_app tool
<div id="root"></div>
<script type="text/jsx">
import { useState } from "react";
import { createRoot } from "react-dom/client";
import { useHivekeep } from "@hivekeep/react";
import { Card, Button, Stack } from "@hivekeep/components";


function App() {
  const { ready } = useHivekeep();
  if (!ready) return <div>Loading...</div>;
  return <Counter />;
}


function Counter() {
  const [count, setCount] = useState(0);
  return (
    <Card>
      <Card.Header>
        <Card.Title>Counter</Card.Title>
      </Card.Header>
      <Card.Content>
        <Stack direction="row" gap="8px" align="center">
          <Button onClick={() => setCount(c => c - 1)}>-</Button>
          <span style={{ fontSize: '2rem' }}>{count}</span>
          <Button onClick={() => setCount(c => c + 1)}>+</Button>
        </Stack>
      </Card.Content>
    </Card>
  );
}


createRoot(document.getElementById("root")).render(<App />);
</script>

Next Steps

Section titled “Next Steps”