Skip to content
eiaserinnysPublic

About

Configuration-based, intentionally indifferent service runner

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

haniel

A service runner that your AI agent can operate.

haniel manages processes, polls git repos, and exposes everything through MCP — so Claude Code can deploy, restart, monitor, and configure your services through natural conversation.

You:    "Deploy the latest changes to api-server"
Claude: haniel_pull(repo="api") → haniel_restart(service="api-server")
        ✅ Pulled 3 commits, api-server restarted successfully.

haniel

CI

The problem

You have a few services running on a machine. You want to:

  • Deploy by pulling from git, not by building Docker images
  • Let your AI agent handle routine ops (restart, rollback, check logs)
  • See what's happening from a dashboard

Existing tools don't quite fit:

Tool Gap
PM2 / systemd No AI interface. Agent must generate shell commands and parse text output.
Docker Compose Assumes containerized workflows. Overkill when you just want to git pull and restart.
Coolify / CapRover Full PaaS with their own deployment model. You're adopting a platform, not a tool.

haniel is a single YAML file + a process that your AI agent already knows how to talk to.

How it works

  1. You write haniel.yaml (or let Claude Code do it) — repos to poll, services to run, how they depend on each other
  2. haniel runs as a service — polls git, manages processes, restarts on crash
  3. Claude Code connects via MCP — every operation is a tool call, not a shell command

For agents: See haniel.yaml.example and Configuration Reference for the full schema.

# haniel.yaml
poll_interval: 60

repos:
  backend:
    url: https://github.com/you/backend.git
    branch: main
    path: ./.services/backend
    release_manifest: deploy/release-manifest.json

services:
  api:
    run: python -m uvicorn app:main --port 8000
    cwd: ./.services/backend
    repo: backend
    ready_timeout: 120
    hooks:
      post_pull: pip install -r requirements.txt
      timeout: 900

Haniel watches the repo, pulls changes, runs the build hook, and restarts the service. Repositories with migrations can add a versioned release manifest so one approval covers preflight, backup, migration, readiness, verification, and automatic recovery.

Features

  • Git polling — watches repositories, pulls on new commits
  • Process management — start, stop, restart with dependency ordering
  • Lifecycle hooks — pre_start and post_pull for prerequisites and builds
  • Migration-aware releases — versioned manifests with backup gates, readiness verification, and automatic recovery
  • Health monitoring — crash detection, exponential backoff, circuit breaker
  • MCP server — full control surface via Streamable HTTP
  • Web dashboard — real-time UI with Claude Code chat panel
  • Runtime config — add/update/remove services without restart
  • Self-update — two-loop architecture for updating its own code
  • Webhooks — Slack, Discord, or JSON on deploys and failures

Quick start

Install

# PowerShell as Administrator (Windows 10+, Python 3.11+)
irm https://raw.githubusercontent.com/eiaserinnys/haniel/main/install-haniel.ps1 | iex

Install on macOS

Install Python 3.11 or newer and git first, plus Node, pnpm or Claude Code when the services need them. There is no automatic tool installer. Install Haniel into the virtual environment of the Python you choose:

python3 -m venv ~/.local/haniel-venv
~/.local/haniel-venv/bin/pip install haniel

Homebrew lives in /opt/homebrew/bin on Apple Silicon and in /usr/local/bin on Intel Macs. The installer and the generated LaunchAgent append these directories to the tool search PATH, but tools are never installed automatically.

The hooks in haniel.yaml.example use Windows venv paths. The shared hook runner does not translate them for macOS, so write POSIX paths such as ./.venv/bin/pip in macOS service hooks.

Service registration installs a user LaunchAgent at ~/Library/LaunchAgents/com.haniel.<name>.plist. It is not loaded during installation; after logging in as the same user, start and manage it with:

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.haniel.runner.plist
launchctl print gui/$(id -u)/com.haniel.runner
launchctl kickstart -k gui/$(id -u)/com.haniel.runner
launchctl bootout gui/$(id -u)/com.haniel.runner

With self-update enabled the agent runs haniel-runner.sh from the Haniel repo, which prepares a release and relaunches on exit codes 10 and 11.

Connect Claude Code

{
  "mcpServers": {
    "haniel": {
      "type": "http",
      "url": "http://localhost:3200/mcp/http"
    }
  }
}

Now Claude Code can operate your infrastructure:

"What services are running?"          → haniel://status
"Show me api-server logs"             → haniel_read_logs(service="api-server")
"Restart the worker"                  → haniel_restart(service="worker")
"Pull and deploy backend"             → haniel_update(service="api")
"Add a new service"                   → haniel_create_service_config(...)

For a normal service, haniel_update pulls its repository and restarts the repository's affected services. If no changes are pending, it does nothing.

Self-update

haniel solves the "surgeon can't operate on themselves" problem with a two-loop design:

WinSW (Windows service)
  └── haniel-runner.ps1  (outer loop — survives updates)
       └── haniel run    (inner loop — the actual service)

When haniel detects changes to its own repo, it exits with code 10. The outer loop runs git pull + pip install and relaunches.

Documentation

Development

git clone https://github.com/eiaserinnys/haniel.git
cd haniel
pip install -e ".[dev]"
pytest

Dashboard frontend (React):

cd dashboard
pnpm install && pnpm run build

License

MIT

About

Configuration-based, intentionally indifferent service runner

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages