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

> Explore the 5 main holaOS entry points and interfaces including Electron desktop, Runtime API, MCP host, hola CLI, and runtime packages. Interact with holaOS easily.

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

---

**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

```bash
npm run desktop:dev

# or

bun run desktop:dev

```

These commands compile and execute the main process from [`apps/desktop/electron/main.ts`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/apps/desktop/electron/main.ts)
- **Compiled output:** `out/dist-electron/main.cjs`
- **Package configuration:** [`apps/desktop/package.json`](https://github.com/holaboss-ai/holaOS/blob/main/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
// 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`](https://github.com/holaboss-ai/holaOS/blob/main/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

```typescript
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

```typescript
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`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/api-server/src/workspace-mcp-host.ts) exports `startWorkspaceMcpHost` and `callWorkspaceTool`. The host is invoked from [`workspace-mcp-sidecar.ts`](https://github.com/holaboss-ai/holaOS/blob/main/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

```bash

# 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:

```bash
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`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/state-store/src/store.ts) implements the core SQLite-backed state store.

## Summary

- **Electron main process** ([`apps/desktop/electron/main.ts`](https://github.com/holaboss-ai/holaOS/blob/main/apps/desktop/electron/main.ts)) – Launch the desktop UI via `npm run desktop:dev`
- **Runtime API server** ([`runtime/api-server/src/index.ts`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/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`.