GitHub - maleus-ai/kepler: A lightweight process orchestrator for Unix based machines - manage services with dependencies, health checks, hooks, and real-time logs

A process orchestrator for managing application lifecycles. Kepler provides a single global daemon that manages multiple configuration files on demand, with support for health checks, file watching, hooks, and more.

Features

• Global daemon with per-config isolation and persistent state
• Docker Compose-compatible dependencies with conditions, timeouts, and restart propagation
• Attached start mode -- kepler start follows logs like docker compose up; Ctrl+C gracefully stops
• Health checks -- Docker-compatible health check configuration
• Lifecycle hooks -- Run commands at init, start, stop, restart, cleanup, and health transitions
• File watching -- Automatic service restart on file changes
• Environment isolation -- Controlled env with ${{ }}$ inline Lua expressions and .env file support
• Lua scripting -- Dynamic config generation with !lua tags and ${{ }}$ expressions
• Privilege dropping -- Run services as specific users/groups with resource limits
• Colored persistent logs -- Real-time streaming with per-service colors, persisted to disk

Installation

# Install latest release
curl -sSfL https://raw.githubusercontent.com/maleus-ai/kepler/master/get-kepler.sh | bash

# Install a specific version
curl -sSfL https://raw.githubusercontent.com/maleus-ai/kepler/master/get-kepler.sh | bash -s v0.11.0

Or build from source (requires Rust 1.85+):

git clone https://github.com/maleus-ai/kepler.git
cd kepler
./install.sh

See Getting Started for full install options, post-install setup, and systemd integration.

Quick Start

1. Create a kepler.yaml configuration file:

services:
  backend:
    command: ["npm", "run", "start"]
    working_dir: ./backend
    restart: always
    healthcheck:
      run: "curl -f http://localhost:3000/health || exit 1"
      interval: 10s
      timeout: 5s
      retries: 3

2. Start the daemon and services:

kepler daemon start -d   # Start daemon in background
kepler start             # Start services, follow logs (Ctrl+C to stop)
kepler start -d          # Return immediately, startup runs in background
kepler start -d --wait   # Block until startup cluster ready, then return

3. Monitor and manage:

kepler ps                # Show service status
kepler logs --follow     # Follow logs
kepler stop              # Stop services (SIGTERM)
kepler stop -s SIGKILL   # Stop services with a specific signal
kepler daemon stop       # Stop daemon

For a ready-to-run example, see example.kepler.yaml.

Documentation

Getting Started

• Getting Started -- Installation, setup, and first config
• CLI Reference -- Complete command reference
• Configuration -- Full YAML schema reference

Core Concepts

• Service Lifecycle -- Status states, start modes, quiescence
• Dependencies -- Conditions, ordering, propagation, timeouts
• Health Checks -- Docker-compatible health checks
• Hooks -- Service lifecycle hooks

Configuration Features

• Environment Variables -- Three-stage expansion, inheritance
• Inline Expressions -- ${{ expr }}$ syntax reference
• Lua Scripting -- Luau sandbox, context, examples
• Log Management -- Storage, buffering, retention, streaming
• File Watching -- Auto-restart on file changes

Security & Operations

• Security Model -- Root, kepler group, socket auth
• Privilege Dropping -- User/group, resource limits

Internals

• Architecture -- Internal implementation, design decisions, diagrams
• Protocol -- Multiplexed IPC wire format
• Testing -- Docker environment, test harnesses, E2E patterns

Project Structure