holaOS Core System Components: The 4 Pillars of a Local‑First Agent Runtime

holaOS is built around four tightly‑coupled components—State Store, API Server, Channel Gateway, and Desktop Application—that together provide a shared, SQLite‑backed workspace for any AI agent.

The holaOS core system is an open‑source, TypeScript‑driven runtime developed by holaboss-ai/holaOS. It enables multiple agents (Claude Code, Codex, the built‑in holaOS agent, and others) to operate within a single, durable workspace with persistent memory and extensible tool access. Understanding these holaOS core system components is essential for developers building custom agent integrations or extending the platform.

The Four Core Components

State Store: SQLite‑Backed Persistence Layer

The State Store is the foundational data layer of holaOS. It persists all workspace metadata, session history, and the semantic memory graph in a compact SQLite database.

Located in [runtime/state-store/src/store.ts](https://github.com/holaboss-ai/holaOS/blob/main/runtime/state-store/src/store.ts), this component provides:

• Workspace record management via RuntimeStateStore.open() and store.getWorkspaceRecord()
• Deterministic state snapshots through a stable JSON‑sorting helper
• Migration logic for seamless schema evolution across versions

The State Store guarantees that all agents share identical context, even across restarts.

import { RuntimeStateStore } from "@holaboss/runtime-state-store";

async function getWorkspaceInfo(workspacePath: string) {
  const store = await RuntimeStateStore.open(workspacePath);
  const ws = await store.getWorkspaceRecord();   // ↳ defined in store.ts
  console.log(`Workspace ${ws.name} (id=${ws.id})`);
}

API Server: Fastify HTTP Interface

The API Server exposes holaOS functionality over HTTP on port 8080. Built with Fastify, it handles workspace capabilities, MCP (Model‑Context‑Protocol) registration, integration wiring, and turn‑level orchestration.

Key implementation in [runtime/api-server/src/workspace-capabilities.ts](https://github.com/holaboss-ai/holaOS/blob/main/runtime/api-server/src/workspace-capabilities.ts):

• CapabilityDefinition schema for describing agent skills
• CapabilityMcpServer parsing for external tool registration
• upsertWorkspaceMcpServerEntry() for runtime MCP server installation

import fetch from "node-fetch";

async function listCapabilities() {
  const resp = await fetch("http://localhost:8080/api/v1/capabilities");
  const caps = await resp.json();   // each entry matches CapabilityDefinition
  console.log("Installed capabilities:", caps.map(c => c.id));
}

import { upsertWorkspaceMcpServerEntry } from
  "@holaboss/runtime-api-server/src/workspace-apps.js";

await upsertWorkspaceMcpServerEntry({
  workspaceId: "root",
  server: {
    id: "local-tts",
    type: "local",
    command: ["tts-server", "--port", "9001"],
    tools: ["textToSpeech"],
  },
});

Channel Gateway: Secure UI‑Runtime Bridge

The Channel Gateway provides an authenticated, multiplexed connection between the desktop UI and the API server. It is implemented in [runtime/channel-gateway/src/manager.ts](https://github.com/holaboss-ai/holaOS/blob/main/runtime/channel-gateway/src/manager.ts).

Core responsibilities:

• Session key generation and validation (via session-key.ts logic)
• Bidirectional streaming of JSON‑encoded events
• Per‑connection policy enforcement to prevent unauthorized runtime access

import { createChannelGateway } from "@holaboss/channel-gateway";

const gateway = createChannelGateway({
  apiUrl: "http://localhost:8080",
  sessionKey: "my‑session‑key",   // obtained from `session-key.ts`
});

gateway.on("event", ev => console.log("Runtime event:", ev));
gateway.send({ type: "ping" });

Desktop Application: Electron Front‑End

The Desktop Application delivers the holaOS user experience. This Electron‑based interface renders HolaApps side‑by‑side with agent interactions and displays the shared memory tree.

Entry point: [apps/desktop/src/main.ts](https://github.com/holaboss-ai/holaOS/blob/main/apps/desktop/src/main.ts)

Capabilities include:

• Window creation and lifecycle management
• Channel Gateway client initialization
• Renderer‑process communication for UI updates

How the Components Interact

The four holaOS core system components form a unified platform through four architectural principles:

1. One shared memory – All agents read/write the same SQLite‑backed semantic memory via the State Store
2. Unified capability model – WorkspaceCapabilityRecord describes invocable skills, integrations, and MCP servers
3. MCP extensibility – The API server dynamically loads external tools (browsers, image generators, etc.)
4. Secure bridge architecture – The Channel Gateway authenticates every UI session before streaming begins

Key Implementation Files

File	Component	Purpose
runtime/state-store/src/store.ts	State Store	Core persistence, migrations, WorkspaceRecord
runtime/api-server/src/workspace-capabilities.ts	API Server	Capability schema, MCP parsing, install helpers
runtime/channel-gateway/src/manager.ts	Channel Gateway	Session management, stream routing, authentication
apps/desktop/src/main.ts	Desktop Application	Electron bootstrap, window creation, gateway wiring
packages/runtime-client/README.md	SDK Documentation	TypeScript client for API server interactions

Summary

• State Store provides durable SQLite persistence for workspace state and semantic memory
• API Server exposes Fastify HTTP endpoints on port 8080 for capabilities and MCP orchestration
• Channel Gateway secures the connection between desktop UI and runtime with session‑key authentication
• Desktop Application delivers the Electron‑based interface for HolaApps and agent collaboration
• MCP extensibility allows runtime registration of external tools without restarts
• Local‑first architecture ensures all data remains on‑device with deterministic state snapshots

Frequently Asked Questions

What database does holaOS use for persistence?

holaOS uses SQLite via the State Store component. The RuntimeStateStore class in runtime/state-store/src/store.ts manages all workspace metadata, session history, and the semantic memory graph in a compact, single‑file database with built‑in migration support.

How does holaOS handle authentication between the UI and runtime?

Authentication is handled by the Channel Gateway. It generates and validates session keys, negotiates per‑connection policies, and establishes bidirectional JSON streams. The gateway prevents unauthorized access to the underlying API server and runtime state.

Can external tools be added to holaOS dynamically?

Yes. The API server's workspace-capabilities.ts implements MCP (Model‑Context‑Protocol) extensibility. Developers call upsertWorkspaceMcpServerEntry() to register local or remote MCP servers at runtime, making new tools immediately available to all agents in the workspace.

Is holaOS suitable for multi‑agent workflows?

Absolutely. The core design principle is one shared memory, multiple agents. Any agent—Claude Code, Codex, or the built‑in holaOS agent—can connect to the same workspace via the API Server and access identical context through the State Store's semantic memory graph.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}