How to Integrate holaOS with Your Existing Workflow: 3 Methods Explained

Yes, you can integrate holaOS with any workflow that supports HTTP requests or Node.js/TypeScript by using its modular Remote API, typed runtime client, or event-driven Channel Gateway.

The holaOS platform from holaboss-ai/holaOS is built as an API-first, modular system designed to drop into your existing infrastructure without requiring a complete rewrite. Its three-layer architecture exposes clean integration points that accept everything from simple HTTP calls to complex event-driven automations, all while maintaining type safety and versioned contracts.

Understanding the holaOS Architecture

Before integrating, you must understand the three loosely-coupled layers that comprise the system. Each layer offers a distinct integration point depending on your workflow requirements.

• Remote API — A Fastify-based HTTP server exposing a versioned REST and WebSocket contract. Located in packages/remote-api/src/server/index.ts, this layer provides the public surface for creating sessions, invoking skills, and managing agent memory. The contract definitions live in packages/remote-api/src/contract/index.ts.

• State Store — A SQLite-backed persistence layer found in runtime/state-store/src/store.ts. This holds all session data, workflow runs, and plugin definitions, queryable either via the API or directly through the runtime-client library for high-performance TypeScript applications.

• Channel Gateway — An connection manager in runtime/channel-gateway/src/manager.ts that translates inbound/outbound events from external services (e.g., Slack, Discord) into the Remote API format. New channels are added by implementing a port in runtime/channel-gateway/src/ports.ts.

Stateless Integration via the Remote API

The fastest way to integrate holaOS into your existing workflow is through stateless HTTP calls to the Remote API. This method requires no local dependencies—only the ability to send HTTP requests from your script, CI pipeline, or web backend.

According to the source code in packages/remote-api/src/contract/index.ts, the API exposes endpoints such as /sessions for session management and /skills/{name} for capability execution. Because the contract is versioned, you can adopt specific endpoints without maintaining a local client library.

import fetch from 'node-fetch';

// Create a new session
const session = await fetch('http://localhost:3000/api/v1/sessions', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ clientId: 'my-workflow' })
}).then(r => r.json());

// Execute a skill (e.g., a "summarize" capability)
const result = await fetch(`http://localhost:3000/api/v1/sessions/${session.id}/skills/summarize`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ text: 'Hello world! This is my data.' })
}).then(r => r.json());

console.log('Summary →', result.output);

Stateful Integration with the Runtime Client

For tighter TypeScript integration, import the runtime client from packages/runtime-client/src/index.ts. This approach provides typed methods, automatic error handling, and direct access to the State Store for fast local reads and writes.

The RuntimeClient class wraps the Remote API contract in a type-safe interface, eliminating the need to manually construct HTTP payloads. This is the preferred method when building long-running Node.js applications that require persistent session management.

import { RuntimeClient } from '@holaOS/runtime-client';

// Initialise the client (points to the local API container)
const client = new RuntimeClient({ baseUrl: 'http://localhost:3000/api/v1' });

async function runWorkflow() {
  // 1️⃣ Create a session
  const sess = await client.sessions.create({ clientId: 'my-workflow' });

  // 2️⃣ Run a skill (e.g., "extract-entities")
  const { output } = await client.skills.execute(sess.id, 'extract-entities', {
    text: 'Hola OS integrates with Slack, Github, and Zapier.'
  });

  console.log('Extracted entities →', output);
}

runWorkflow();

Event-Driven Integration Using the Channel Gateway

To add holaOS as the "brain" behind existing communication tools like Slack or Discord, use the Channel Gateway. This layer listens to external events and forwards them to the Remote API, enabling bidirectional communication without modifying your chat platform's core logic.

You implement a new channel by creating a port class that adheres to the interface defined in runtime/channel-gateway/src/ports.ts. The gateway manager in runtime/channel-gateway/src/manager.ts then handles event routing and session lifecycle management automatically.

import { ChannelGateway } from '@holaOS/channel-gateway';
import { SlackPort } from '@holaOS/channel-gateway/src/ports';

// Initialise the gateway and add a Slack port
const gateway = new ChannelGateway({ apiBase: 'http://localhost:3000/api/v1' });
gateway.addPort(new SlackPort({
  token: process.env.SLACK_BOT_TOKEN!,
  signingSecret: process.env.SLACK_SIGNING_SECRET!
}));

gateway.start(); // now forwards Slack events to Hola OS

Docker Deployment for CI/CD Environments

All components ship as Docker containers orchestrated via docker-compose.yml. You can deploy the entire stack—including the Remote API, State Store, and optional Channel Gateway ports—into your CI environment, local development machine, or Kubernetes cluster with minimal configuration changes.

The containerized architecture means you can run holaOS alongside your existing services without version conflicts or environment drift. Simply reference the official Docker Compose configuration to wire the API container (port 3000) to your internal network.

Summary

• holaOS exposes three integration layers: the Remote API (HTTP/WebSocket), the State Store (SQLite persistence), and the Channel Gateway (event routing).
• Stateless workflows call the REST endpoints defined in packages/remote-api/src/contract/index.ts directly using any HTTP client.
• Stateful applications should import @holaOS/runtime-client and instantiate the RuntimeClient class for type-safe session management.
• Event-driven systems implement custom ports in runtime/channel-gateway/src/ports.ts to connect external services like Slack.
• All components run in Docker via the included docker-compose.yml, enabling seamless CI/CD integration.

Frequently Asked Questions

Can I integrate holaOS without using TypeScript?

Yes. The Remote API in packages/remote-api/src/server/index.ts exposes standard HTTP endpoints that accept JSON from any language. You can call /api/v1/sessions and /api/v1/skills/* using Python, Go, curl, or any HTTP-compatible tool without installing Node.js dependencies.

How does the SQLite state store handle concurrent workflow runs?

The State Store implementation in runtime/state-store/src/store.ts uses SQLite with proper transaction isolation to handle concurrent reads and writes from multiple workflow instances. For high-throughput scenarios, you can replace this layer with Postgres while preserving the same API contract in packages/remote-api/src/contract/index.ts.

What is required to add a custom communication channel?

You must implement a new port class following the interface in runtime/channel-gateway/src/ports.ts. This class translates your external service's events (e.g., email, SMS) into the standardized format expected by the Channel Gateway manager in runtime/channel-gateway/src/manager.ts, which then routes events to the Remote API.

Is the Remote API contract stable for production use?

Yes. The contract is explicitly versioned and defined in packages/remote-api/src/contract/index.ts, ensuring backward compatibility for existing integrations. The Fastify server implementation in packages/remote-api/src/server/index.ts validates all requests against this schema, preventing breaking changes from affecting your workflow.

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