Getting Started

Welcome to HeadyOS Documentation. HeadyOS is a comprehensive orchestration platform that combines system architecture, AI intelligence, and automation capabilities into a unified framework.

Quick Start

Clone the Repository

bash

git clone https://github.com/headyos/heady-core.git
cd heady-core

Install Dependencies

bash

npm install
npm run bootstrap

Run the System

bash

npm start

Key Concepts

Before diving deep, understand these core concepts:

Services: Autonomous agents providing specific functionality
Pipelines: Orchestrated workflows combining multiple stages
Latent Space: Vector memory system for semantic operations
MCP Tools: Model Context Protocol tools for AI integration
Liquid Nodes: Protocol-bridging communication nodes

Installation

System Requirements

Node.js 18.x or higher
npm 8.x or higher
Docker 20.10+ (for containerized deployments)
4GB RAM minimum, 8GB recommended
macOS 10.15+, Linux (Ubuntu 20.04+), or Windows 10+

Installation Steps

1. Install Node.js

Download from nodejs.org or use a version manager:

bash

# Using nvm
nvm install 18
nvm use 18

2. Clone Repository

bash

git clone https://github.com/headyos/heady-core.git
cd heady-core
git checkout main

3. Install Dependencies

bash

npm install
npm run build

Docker Installation

                        dockerfile
                        FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 3000
CMD ["npm", "start"]
                    

Configuration

HeadyOS uses YAML-based configuration files to control system behavior. All configs live in the configs/ directory.

service-catalog.yaml

Defines all services available in the system with their endpoints and capabilities.

yaml

services:
  - id: auth-service
    name: Authentication Service
    endpoint: http://localhost:3001
    capabilities:
      - authenticate
      - authorize
      - token-refresh
    status: active
  
  - id: data-pipeline
    name: Data Processing Pipeline
    endpoint: http://localhost:3002
    capabilities:
      - ingest
      - transform
      - export
    status: active

hcfullpipeline.yaml

Configures the HC Full Pipeline with stages and transformations.

yaml

pipeline:
  name: hc-full-pipeline
  version: 3.0.0
  stages:
    - name: intake
      type: source
      config:
        retries: 3
    - name: process
      type: transform
      config:
        timeout: 60000
    - name: output
      type: sink
      config:
        compression: gzip

resource-policies.yaml

Defines resource allocation and budgets.

yaml

resources:
  cpu:
    limit: 4000m
    request: 1000m
  memory:
    limit: 8Gi
    request: 2Gi
  storage:
    limit: 100Gi
budgets:
  monthly_compute: 10000
  monthly_storage: 5000

Configuration Reference Table

File	Purpose	Key Sections
service-catalog.yaml	Service registry and endpoints	services, capabilities, status
hcfullpipeline.yaml	Pipeline orchestration	stages, transforms, routing
resource-policies.yaml	Resource constraints	cpu, memory, storage, budgets
headymcp.json	MCP configuration	tools, adapters, protocol bridges

API Reference

Core Endpoints

GET /api/health

Check system health status.

bash

curl http://localhost:3000/api/health

GET /api/services

List all registered services.

bash

curl http://localhost:3000/api/services \
  -H "Authorization: Bearer YOUR_TOKEN"

POST /api/pipeline/execute

Execute a pipeline with input data.

bash

curl -X POST http://localhost:3000/api/pipeline/execute \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline": "hc-full-pipeline",
    "data": {"input": "value"}
  }'

Architecture Overview

HeadyOS is built on a modular, service-oriented architecture that emphasizes scalability, flexibility, and integration.

System Layers

API Layer: HTTP/WebSocket endpoints for external communication
Service Layer: Autonomous services handling specific domains
Pipeline Layer: Orchestration and workflow management
Integration Layer: MCP tools, Liquid Nodes, protocol bridges
Memory Layer: Latent space vector storage and semantic search
Persistence Layer: Database, file storage, caching

Key Components

Service Registry

Central registry tracking all services, their capabilities, status, and endpoints. Enables dynamic service discovery and load balancing.

Pipeline Engine

Orchestrates multi-stage workflows with conditional routing, error handling, and rollback capabilities. Supports both linear and DAG-based pipelines.

Latent Space Vector Memory

Powered by 3 Colab Pro+ runtimes, provides semantic search and vector storage for operation history and knowledge base.

Protocol Bridge (Liquid Nodes)

Translates between MCP, HTTP, WebSocket, UDP, MIDI, and TCP protocols. Enables seamless integration of diverse systems.

Deployment Guide

Development Deployment

bash

npm run dev

Production Deployment on Render

HeadyOS deploys seamlessly to Render via render.yaml configuration.

                        bash
                        # Deploy to Render
render deploy --name heady-core-prod
                    

Docker Deployment

bash

# Build Docker image
docker build -t heady-os:latest .

# Run container
docker run -p 3000:3000 \
  -e NODE_ENV=production \
  heady-os:latest

Kubernetes Deployment

For large-scale deployments, use Kubernetes manifests stored in deploy/k8s/.

bash

kubectl apply -f deploy/k8s/namespace.yaml
kubectl apply -f deploy/k8s/deployment.yaml
kubectl apply -f deploy/k8s/service.yaml

Environment Variables

Variable	Description	Default
NODE_ENV	Environment (development/production)	development
PORT	Server port	3000
LOG_LEVEL	Logging level (debug/info/warn/error)	info
DATABASE_URL	Database connection string	sqlite://./data.db