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

> Integrate holaOS with your workflow using its Remote API, typed runtime client, or Channel Gateway. Discover three powerful methods for seamless integration and boost your productivity today.

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

---

**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`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/packages/remote-api/src/contract/index.ts).

- **State Store** — A SQLite-backed persistence layer found in [`runtime/state-store/src/store.ts`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/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.

```typescript
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`](https://github.com/holaboss-ai/holaOS/blob/main/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.

```typescript
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`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/channel-gateway/src/ports.ts). The gateway manager in [`runtime/channel-gateway/src/manager.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/channel-gateway/src/manager.ts) then handles event routing and session lifecycle management automatically.

```typescript
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`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/channel-gateway/src/ports.ts) to connect external services like Slack.
- All components run in Docker via the included [`docker-compose.yml`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/packages/remote-api/src/server/index.ts) validates all requests against this schema, preventing breaking changes from affecting your workflow.