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

> Discover the 4 core pillars of holaOS: State Store, API Server, Channel Gateway, and Desktop Application. Learn how these components create a shared SQLite-backed workspace for AI agents.

- Repository: [holaboss.ai/holaOS](https://github.com/holaboss-ai/holaOS)
- Tags: architecture
- Published: 2026-08-15

---

**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)](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.

```typescript
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)](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

```typescript
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));
}

```

```typescript
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)](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`](https://github.com/holaboss-ai/holaOS/blob/main/session-key.ts) logic)
- **Bidirectional streaming** of JSON‑encoded events
- **Per‑connection policy enforcement** to prevent unauthorized runtime access

```typescript
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)](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`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/state-store/src/store.ts) | State Store | Core persistence, migrations, `WorkspaceRecord` |
| [`runtime/api-server/src/workspace-capabilities.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/api-server/src/workspace-capabilities.ts) | API Server | Capability schema, MCP parsing, install helpers |
| [`runtime/channel-gateway/src/manager.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/channel-gateway/src/manager.ts) | Channel Gateway | Session management, stream routing, authentication |
| [`apps/desktop/src/main.ts`](https://github.com/holaboss-ai/holaOS/blob/main/apps/desktop/src/main.ts) | Desktop Application | Electron bootstrap, window creation, gateway wiring |
| [`packages/runtime-client/README.md`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/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.