How Is the API Structured in HollaOS? Server, Routes, and SDK Explained

HollaOS exposes a RESTful HTTP API built on Fastify with all routes mounted under /api/v1/, organized by domain (workspaces, sessions, memory, integrations, apps), and consumed through a typed TypeScript SDK.

The HollaOS API structure follows a clean separation between server-side route handlers and a client-side SDK. According to the holaboss-ai/holaOS source code, the runtime functionality is delivered through a Fastify-based HTTP layer with domain-specific routers and a matching TypeScript client that abstracts network details.

---

Server Architecture: Fastify Foundation

The API server launches from runtime/api-server/src/index.ts, which delegates instance creation to buildRuntimeApiServer in runtime/api-server/src/app.ts. This function wires all domain routers, configures Pino logging, and attaches the apiError middleware for normalized error responses.

All endpoints share the base path /api/v1/ and are grouped by functional domain. Each domain has a dedicated router module that registers HTTP verbs and validation schemas.

Domain Organization

Domain	Router File	Key Endpoints
Workspaces	runtime/api-server/src/workspace-*.ts (implied)	GET /workspaces, POST /workspaces, PATCH /workspaces/:id, POST /workspaces/:id/activate
Sessions	runtime/api-server/src/workspace-sessions.ts	GET /sessions, POST /sessions, PATCH /sessions/:id, DELETE /sessions/:id
Memory	runtime/api-server/src/workspace-memory.ts	GET /memory/:workspaceId, POST /memory/:workspaceId, PATCH /memory/:workspaceId/:nodeId
Integrations	runtime/api-server/src/workspace-integrations.ts (implied)	GET /integrations, POST /integrations, PATCH /integrations/:id, DELETE /integrations/:id
Apps	runtime/api-server/src/workspace-apps.ts	GET /apps, POST /apps/ensure-running

Route handlers delegate to service classes that interact with the state store. Error handling and fatal-error recovery are centralized in the server entry point.

---

Route Implementation Example

The apps domain demonstrates the registration pattern used across all modules:

// runtime/api-server/src/workspace-apps.ts
export function registerWorkspaceAppsRoutes(app: FastifyInstance) {
  app.get("/api/v1/apps", listAppsHandler);
  app.post(
    "/api/v1/apps/ensure-running",
    {
      schema: { body: ensureRunningSchema },
      timeout: 300_000,
    },
    ensureAppsRunningHandler,
  );
}

Each route specifies:

• HTTP verb and path (prefixed with /api/v1/)
• Validation schema for request bodies
• Timeout configuration (300 seconds for long-running app startup)
• Handler function implementing business logic

---

Client SDK: Typed Abstraction Layer

The TypeScript SDK (packages/runtime-client) mirrors the server structure with method groups that correspond to each API domain. The core request factory in packages/runtime-client/src/request.ts handles base URL resolution, JSON serialization, retries, and timeouts.

SDK Method Factory Pattern

Each domain exports a factory function that builds typed methods:

// Example: workspaces.ts (client)
export function makeWorkspacesMethods(request: RequestFn): WorkspacesMethods {
  return {
    list(params) { /* GET /api/v1/workspaces */ },
    get(id) { /* GET /api/v1/workspaces/:id */ },
    create(payload) { /* POST /api/v1/workspaces */ },
    update(id, payload) { /* PATCH /api/v1/workspaces/:id */ },
    delete(id, options) { /* DELETE /api/v1/workspaces/:id */ },
    activate(id) { /* POST /api/v1/workspaces/:id/activate */ },
    ensureAppsRunning(id) { /* POST /api/v1/apps/ensure-running */ },
  };
}

All method groups are composed in packages/runtime-client/src/index.ts and exposed through a single entry point:

import { createRuntimeClient } from "@/packages/runtime-client";

const client = createRuntimeClient("http://localhost:3060");

---

Practical SDK Usage

Creating a Workspace

await client.workspaces.create({
  name: "Demo Workspace",
  harness: "default",
  status: "active",
  onboarding_status: "pending",
});

Listing Sessions

const { items: sessions } = await client.sessions.list({ limit: 20 });
console.log("Running sessions:", sessions);

Activating a Workspace

await client.workspaces.activate("workspace-abc123");

---

Running the API Server

# Start the runtime API (listening on 127.0.0.1:3060 by default)

node runtime/api-server/src/index.js

Graceful shutdown and fatal error handling are implemented directly in the entry point.

---

Key Source Files

Path	Purpose
runtime/api-server/src/index.ts	Server entry point, graceful shutdown wiring
runtime/api-server/src/app.ts	Fastify instance builder, router registration
runtime/api-server/src/workspace-apps.ts	Apps domain routes
runtime/api-server/src/workspace-sessions.ts	Sessions domain routes
runtime/api-server/src/workspace-memory.ts	Memory domain routes
packages/runtime-client/src/request.ts	HTTP abstraction with retry/timeout
packages/runtime-client/src/methods/workspaces.ts	Workspace client methods
packages/runtime-client/src/methods/sessions.ts	Session client methods
packages/runtime-client/src/methods/memory.ts	Memory client methods
packages/runtime-client/src/methods/integrations.ts	Integration client methods
packages/runtime-client/src/index.ts	Public SDK export (createRuntimeClient)

---

Summary

• HollaOS API structure uses Fastify as the HTTP framework with all routes under /api/v1/
• Domains (workspaces, sessions, memory, integrations, apps) each have dedicated router modules
• Route handlers delegate to service classes; errors are normalized via middleware
• The TypeScript SDK (packages/runtime-client) provides fully typed, ergonomic client methods
• Factory functions generate domain-specific method groups that mirror server routes
• Versioning under /api/v1/ supports future API evolution without breaking changes

---

Frequently Asked Questions

What HTTP framework does HollaOS use for its API?

HollaOS uses Fastify as its HTTP framework. The server instance is created by buildRuntimeApiServer in runtime/api-server/src/app.ts, which configures routing, logging with Pino, and error handling middleware.

How is the HollaOS API versioned?

All routes are prefixed with /api/v1/, establishing a clear versioning boundary. This allows future API versions to be introduced under /api/v2/ without disrupting existing integrations.

What domains does the HollaOS API cover?

The API spans six primary domains: Workspaces (environment management), Sessions (execution contexts), Memory (semantic storage), Integrations (external service connectors), Apps (application lifecycle), and Cronjobs/Tools (background job scheduling).

How does the TypeScript SDK handle HTTP details?

The SDK centralizes HTTP concerns in packages/runtime-client/src/request.ts, which manages base URL resolution, JSON parsing, automatic retries, and configurable timeouts. Domain-specific modules like workspaces.ts and sessions.ts provide typed methods that consumers call directly.

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