holaOS

Executes agents within a structured workspace environment that persists state across sessions, using a three-layer architecture (Desktop UI → Runtime API Server → Agent Harness) that decouples the operator interface from execution logic. The runtime manages agent lifecycle via SQLite-backed state store and compiles 'Run Plans' that define agent behavior as environment contracts rather than hard-coded harness logic, enabling agents to evolve their own execution patterns based on workspace structure.

Manages Model Context Protocol (MCP) tool servers as the primary mechanism for projecting agent capabilities into the runtime environment. The runtime hosts MCP servers, maintains their lifecycle, and exposes tools through a schema-based function registry that agents can discover and invoke. Tools are defined declaratively in app.runtime.yaml manifests and integrated via Bridge SDK, enabling dynamic capability composition without modifying core agent logic.

Abstracts agent execution logic behind a swappable 'Agent Harness' interface that decouples the runtime environment from specific LLM implementations or agent reasoning patterns. Different harness implementations can be plugged in (e.g., ReAct pattern, tool-use agents, planning-based agents) without modifying the runtime, enabling multi-model support and experimentation with different agent architectures.

Exposes runtime functionality through a Fastify-based HTTP API server (typically port 5160) that handles workspace management, run compilation, tool invocation, memory recall, and state queries. The API server is the primary integration point for external clients (desktop application, custom tools, third-party systems) and provides RESTful endpoints for all runtime operations.

Uses SQLite as the primary persistence layer for all runtime state including workspace configuration, agent execution history, memory surfaces, and run plans. The state store implements workspace-scoped data partitioning, enabling logical isolation of state across workspaces while maintaining a single SQLite database. State queries and updates are synchronous, providing immediate consistency for agent execution.

Implements a memory system that persists agent observations, decisions, and learned patterns across sessions using the state store (SQLite). Memory surfaces are exposed through the workspace model, and agents can recall relevant context during execution via memory recall mechanisms that inject historical state into the current run plan. This enables agents to maintain continuity of knowledge and adapt behavior based on past interactions without explicit prompt engineering.

Compiles natural language agent instructions into 'Run Plans' — structured execution specifications that define the sequence of agent actions, tool invocations, and state transitions. The runtime's run compilation system translates user intent from natural language space into code entity space (runtime processes and state), managing the full lifecycle of agent execution including tool invocation sequencing, error handling, and state persistence. Run plans are executable specifications that can be inspected, modified, and replayed.

Organizes agent environments into isolated workspaces that encapsulate configuration, tools, memory surfaces, and execution context. Workspaces are defined through app.runtime.yaml manifests and managed by the desktop application, providing a structural boundary for agent capabilities and state. Each workspace maintains its own tool registry, memory store, and execution context, enabling multi-tenant or multi-project isolation within a single holaOS instance.

Provides an Electron-based desktop shell (operator-facing UI) that communicates with the embedded runtime via a type-safe IPC bridge (window.electronAPI) and local HTTP server (typically port 5160). The desktop application handles workspace creation, model configuration, agent progress visualization, and workspace switching. The IPC bridge abstracts runtime communication, enabling the desktop to invoke runtime operations and receive state updates without direct HTTP coupling.

Uses declarative YAML manifests (app.runtime.yaml) to define agent application structure, including tool definitions, workspace configuration, memory surfaces, and execution parameters. The manifest system enables developers to specify agent capabilities and behavior through configuration rather than code, with the runtime parsing and validating manifests at startup. Manifests are versioned and can be updated without redeploying the entire application.

Provides two complementary SDKs for building agent applications: Bridge SDK (@holaboss/bridge) for runtime integration and tool registration, and App SDK (@holaboss/app-sdk) for workspace and memory surface access. Both SDKs are TypeScript-first and provide type-safe abstractions over runtime APIs, enabling developers to build agent applications without direct HTTP coupling to the runtime.

Enables agents to modify their own workspace configuration, tool registry, and memory surfaces during execution, supporting self-evolution patterns where agents can adapt their capabilities based on learned patterns or environmental changes. Agents can update app.runtime.yaml manifests, register new tools, or modify memory surfaces through runtime APIs, with changes persisted to the state store and reflected in subsequent runs.

Supports proactive agent execution through background scheduling mechanisms that enable agents to run autonomously on defined schedules or event triggers, rather than only responding to explicit user requests. The runtime manages agent lifecycle and scheduling, enabling long-running agents that can perform continuous monitoring, learning, or maintenance tasks without user interaction.