Nexus is a zero-config multi-channel platform built on Kailash Core SDK that deploys workflows as API + CLI + MCP simultaneously. The Ruby gem wraps the Rust Nexus engine via native extensions and provides Rack middleware integration.

Features

Zero Configuration: Deploy workflows instantly without boilerplate
Multi-Channel Access: API, CLI, and MCP from a single deployment
Unified Sessions: Consistent session management across all channels
Enterprise Features: Health monitoring, plugins, event system, logging
DataFlow Integration: Automatic CRUD API generation from database models
Rack Integration: Mount Nexus as Rack middleware alongside Rails/Sinatra
Handler DSL: Register Ruby blocks as handlers deployed to all channels

Install

gem install kailash-nexus

Or in Gemfile:

gem "kailash-nexus"

Quick Start

require "kailash/nexus"

# Create workflow
workflow = create_my_workflow

# Deploy to all channels at once
nexus = Kailash::Nexus.new(workflow)
nexus.run(port: 8000)

# Now available via:
# - HTTP API: POST http://localhost:8000/api/workflow/{workflow_id}
# - CLI: nexus run {workflow_id} --input '{"key": "value"}'
# - MCP: Connect via MCP client (Claude Desktop, etc.)

Handler Registration

require "kailash/nexus"

app = Kailash::Nexus::App.new(port: 3000)

# Register handler -- deployed to all channels at once
app.handler("greet", description: "Greet a user") do |params|
  { message: "Hello, #{params[:name]}!" }
end

app.start

# HTTP: POST http://localhost:3000/api/greet
# CLI:  nexus run greet --name "World"
# MCP:  Available as MCP tool

Key Concepts

Zero-Config Platform

Nexus eliminates boilerplate:

No manual routes - Automatic API generation from workflows
No CLI arg parsing - Automatic CLI creation
No MCP server setup - Automatic MCP integration
Unified deployment - One command for all channels

Multi-Channel Architecture

Single deployment, three access methods:

HTTP API: RESTful JSON endpoints
CLI: Command-line interface
MCP: Model Context Protocol server

Unified Sessions

Consistent session management:

Cross-channel session tracking
Session state persistence
Session-scoped workflows
Concurrent session support

Enterprise Features

Production-ready capabilities:

Health monitoring endpoints
Plugin system for extensibility
Event system for integrations
Comprehensive logging and metrics

Integration Patterns

With DataFlow (Database-Backed Handlers)

require "kailash/nexus"
require "kailash/dataflow"

db = Kailash::DataFlow.new do |config|
  config.database_url = ENV["DATABASE_URL"]
end

db.model "User" do |m|
  m.string :name
  m.string :email
end

# Auto-generates CRUD endpoints for all models
nexus = Kailash::Nexus.new(db.workflows)
nexus.run(port: 8000)

# GET    /api/User/list
# POST   /api/User/create
# GET    /api/User/read/:id
# PUT    /api/User/update/:id
# DELETE /api/User/delete/:id

With Kaizen (Agent Platform)

require "kailash/nexus"
require "kailash/kaizen"

app = Kailash::Nexus::App.new(port: 3000)

app.handler("agent_chat", description: "Chat with AI agent") do |params|
  delegate = Kailash::Kaizen::Delegate.new(model: ENV["LLM_MODEL"])
  result = delegate.run_sync(params[:message])
  { response: result }
end

app.start  # Agents accessible via API, CLI, and MCP

With Core SDK (Custom Workflows)

require "kailash"
require "kailash/nexus"

registry = Kailash::Registry.new
builder = Kailash::WorkflowBuilder.new
builder.add_node("NoOpNode", "start", {})
workflow = builder.build(registry)

nexus = Kailash::Nexus.new(workflow)
nexus.run(port: 8000)

With Rack (Middleware)

# config.ru
require "kailash/nexus"

nexus = Kailash::Nexus.new(my_workflows)

# Mount Nexus as Rack middleware
use Kailash::Nexus::Middleware, nexus: nexus
run MyRailsApp

Standalone Platform

require "kailash/nexus"

app = Kailash::Nexus::App.new(
  host: "0.0.0.0",
  port: 3000,
  preset: :enterprise
)

app.cors(origins: ["https://app.example.com"])
app.rate_limit(max_requests: 100, window_secs: 60)

app.handler("status", description: "Platform status") do |_params|
  app.health_check
end

app.start

Deployment Patterns

Development

nexus = Kailash::Nexus.new(workflows)
nexus.run(port: 8000)  # Single process

Production (Docker)

app = Kailash::Nexus::App.new(
  host: "0.0.0.0",
  port: 3000,
  preset: :enterprise
)

# Register handlers...

app.start  # Host/port configured at init

With Puma (Multi-Worker)

# config/puma.rb
workers 4
threads 2, 4
port 3000

# config.ru
require "kailash/nexus"
nexus = Kailash::Nexus.new(my_workflows)
use Kailash::Nexus::Middleware, nexus: nexus
run MyApp

With Load Balancer

# Deploy multiple Nexus instances behind nginx/traefik
docker-compose up --scale nexus=3

Critical Rules

Use Nexus for workflow platforms instead of building raw Rack/Sinatra/Rails API routes
Register workflows or handlers, not individual routes
Leverage unified sessions across channels
Enable health monitoring in production
Use plugins for custom behavior
NEVER mix raw Rack routes with Nexus for the same endpoints
NEVER implement manual API/CLI/MCP servers when Nexus can do it
NEVER skip health checks in production

Channel Comparison

Feature	API	CLI	MCP
Access	HTTP	Terminal	MCP Clients
Input	JSON	Args/JSON	Structured
Output	JSON	Text/JSON	Structured
Sessions	yes	yes	yes
Auth	yes	yes	yes
Streaming	yes	yes	yes

Related Skills

01-core-sdk - Core workflow patterns
02-dataflow - Auto CRUD API generation
04-kaizen - AI agent deployment
05-kailash-mcp - MCP channel details

Support

For Nexus-specific questions, invoke:

nexus-specialist - Nexus implementation and deployment
release-specialist - Production deployment patterns
``decide-framework skill - When to use Nexus vs other approaches