holaOS Entry Points and Interfaces: 5 Ways to Interact with the System

holaOS provides five core interfaces for interaction: the Electron desktop main process, the Runtime API HTTP server, the MCP host for agent tools, the hola CLI wrapper, and specialized runtime packages for storage and tool execution.

The open-source holaOS repository (holaboss-ai/holaOS) exposes multiple well-defined entry points that allow developers to drive the system programmatically, through its UI, or via standard AI agent protocols. Whether you're building automations, integrating with external tools, or launching the full desktop environment, understanding these interfaces is essential for effective development.

Electron Desktop Main Process – The Primary UI Entry Point

The Electron main process serves as the host for the holaOS workspace, apps, and agents. This is the entry point users typically encounter first.

How to Launch

npm run desktop:dev

# or

bun run desktop:dev

These commands compile and execute the main process from apps/desktop/electron/main.ts, which produces out/dist-electron/main.cjs. The main process loads the bundled frontend and establishes a connection to the local Runtime API.

Source Location

• Implementation: apps/desktop/electron/main.ts
• Compiled output: out/dist-electron/main.cjs
• Package configuration: apps/desktop/package.json

Runtime API Server – HTTP JSON-RPC Interface

The Runtime API server provides the primary HTTP interface for all workspace-level operations, including memory management, skills, tools, and apps.

Starting the Server Programmatically

// TypeScript — matches the entry point in src/index.ts
import { buildRuntimeApiServer } from "./app.js";

const api = buildRuntimeApiServer({ logger: true });
await api.listen({ port: 3060, host: "127.0.0.1" });

Configuration and Startup

Aspect	Details
Default port	3060
Environment variable	SANDBOX_RUNTIME_API_PORT
Bootstrap file	runtime/api-server/src/index.ts
Isolated startup script	scripts/runtime-start-isolated.mjs

This server is consumed by the desktop app, CLI tools, and any remote clients requiring programmatic access to holaOS functionality.

MCP Host – Model Context Protocol Interface

The MCP host implements the Model Context Protocol standard, exposing workspace-defined tools so AI agents can discover and invoke them.

Starting an MCP Host for a Workspace

import { startWorkspaceMcpHost } from "./workspace-mcp-host.ts";

const request = {
  workspace_dir: "/path/to/ws",
  catalog_json_base64: "...",   // Base64-encoded JSON catalog
  host: "127.0.0.1",
  port: 4000,
  server_name: "my-mcp"
};

await startWorkspaceMcpHost(request);

Calling Workspace Tools via MCP

import { callWorkspaceTool } from "./workspace-mcp-host.ts";

const result = await callWorkspaceTool(request, "myTool", { arg1: "value" });
console.log(result.content);

Key Methods

• listTools – Returns available tools in the workspace catalog
• callTool – Executes a specific tool with provided arguments

Source: runtime/api-server/src/workspace-mcp-host.ts exports startWorkspaceMcpHost and callWorkspaceTool. The host is invoked from workspace-mcp-sidecar.ts or directly via CLI requests.

CLI Wrapper Script – The hola Command

The hola CLI provides convenient high-level commands that orchestrate the underlying entry points.

Installation and Usage

# One-line install, then use directly

hola <subcommand>

# Or via npx

npx hola <subcommand>

Available Commands

Command	Purpose
hola dev	Launches the desktop app in development mode
hola start	Starts the API server and optionally the UI
hola install	Sets up dependencies and environment

The hola start command supports runtime configuration:

hola start --runtime-port 3060   # launches API server then UI

Source: scripts/hola.mts implements the command-dispatch logic.

State Store and Helper Runtimes – Low-Level Interfaces

Several specialized packages expose their own Node.js entry points for storage, vector search, and tool harness capabilities.

Available Runtime Packages

Package	Capability	Invocation
runtime/state-store	SQLite-backed state storage	npm run runtime:state-store:install then npm run runtime:state-store:test
runtime/harness-host	Tool execution environment	runtime:* npm scripts

These are typically consumed by the API server rather than accessed directly, but they represent valid programmatic entry points for advanced use cases.

Key file: runtime/state-store/src/store.ts implements the core SQLite-backed state store.

Summary

• Electron main process (apps/desktop/electron/main.ts) – Launch the desktop UI via npm run desktop:dev
• Runtime API server (runtime/api-server/src/index.ts) – HTTP JSON-RPC interface on port 3060 by default
• MCP host (runtime/api-server/src/workspace-mcp-host.ts) – Standard protocol for agent tool access
• hola CLI (scripts/hola.mts) – Unified command wrapper for common operations
• Helper runtimes – Specialized packages for storage and tool execution under runtime/*

Frequently Asked Questions

What is the default port for the holaOS Runtime API server?

The Runtime API server listens on port 3060 by default. You can override this by setting the SANDBOX_RUNTIME_API_PORT environment variable before starting the server.

Can I interact with holaOS without using the desktop application?

Yes. The Runtime API server and MCP host provide full HTTP-based access to holaOS functionality. You can start these components independently using scripts/runtime-start-isolated.mjs or programmatically via buildRuntimeApiServer().

How do I expose custom tools to AI agents in holaOS?

Use the MCP host interface. Create a workspace tool catalog, encode it as Base64, and pass it to startWorkspaceMcpHost() from runtime/api-server/src/workspace-mcp-host.ts. Agents can then discover and call your tools via standard MCP methods.

What is the difference between hola dev and hola start?

hola dev launches the Electron desktop application in development mode with hot reloading. hola start is more flexible—it can launch just the API server, or both the server and UI, and accepts configuration flags like --runtime-port.

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