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.
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.
- You write
haniel.yaml(or let Claude Code do it) — repos to poll, services to run, how they depend on each other - haniel runs as a service — polls git, manages processes, restarts on crash
- Claude Code connects via MCP — every operation is a tool call, not a shell command
For agents: See
haniel.yaml.exampleand 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: 900Haniel 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.
- Git polling — watches repositories, pulls on new commits
- Process management — start, stop, restart with dependency ordering
- Lifecycle hooks —
pre_startandpost_pullfor 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
# PowerShell as Administrator (Windows 10+, Python 3.11+)
irm https://raw.githubusercontent.com/eiaserinnys/haniel/main/install-haniel.ps1 | iexInstall 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 hanielHomebrew 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.runnerWith 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.
{
"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.
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.
- Configuration Reference
- Specifications
- ADR-0001: WinSW over NSSM
- ADR-0002: Self-update architecture
- ADR-0003: Directory structure
git clone https://github.com/eiaserinnys/haniel.git
cd haniel
pip install -e ".[dev]"
pytestDashboard frontend (React):
cd dashboard
pnpm install && pnpm run buildMIT
