Hydra Orchestrator

What this is

Hydra Orchestrator is a local-first system for orchestrating tasks and managing workflows, currently in public alpha. At its core it is a file-based task queue (tasks/todo/ → tasks/doing/ → tasks/done//tasks/blocked/) that schedules, dispatches, and validates discrete units of work ("tasks") across local workers — AI agents and scripts — with no mandatory network dependency for local work. Tasks are schema-validated contracts, not free-form prompts: each one declares its own scope, dependencies, and permission range before a worker is allowed to act on it.

Why it exists

Hydra follows a classic, old-school local Unix-style architecture on purpose: a file-based queue, shell/Perl automation, standard CLI tools (git, bash, jq, curl, …), explicit process boundaries, plain-text logs, and Git as durable history — not a daemon/service architecture, not a database-backed queue, and not a framework layer. The problem it solves is running AI-driven and scripted work as auditable, boundary-respecting units instead of ambient agent trust: every task states exactly what it may touch before it runs, every change is committed, and the runtime that executes work is kept separate from the source checkout that defines it.

What works today

See Public Alpha Status for the full, sourced breakdown of what is stable, what may still change incompatibly, and which unusual alpha rules are intentional rather than defects. Substantiated by current code, not just prose:

• Local-first task orchestration — the file-based queue itself.
• Source/runtime separation — enforced by lib/Hydra/Layout.pm and bin/hydra-layout.
• Protected process-queue state — only tasks/doing/ is executable; workers do not silently move task files.
• Explicit task contracts — docs/TICKET_SCHEMA.md plus scripts/validate_task.sh enforce task shape.
• Explicit dependency scheduling — Depends-On: is parsed and enforced by scripts/lib/task_selection_precheck.sh.
• Worker/model routing — Required-Worker, Capability, and Delegation-Objective drive routing against live registry health.
• Audit trails — Git history for both the source repo and the local process/ pipeline state.
• Head runner pull protocol — a working poll/filter/claim/copy implementation (scripts/head-pull.sh and related scripts); whether a specific remote Head is online is runtime state, checked live, not assumed from the docs.

Not everything is finished. Worker-registry economic/trust fields, full VZTEC provider-capsule enforcement, the project-owned process-repository lease/certificate model, and complete command-level permission sandboxing are all partial or may change incompatibly — see Public Alpha Status before relying on them.

What's unusual here — read before you touch anything

These are intentional engineering constraints of running Hydra today, not missing features. Understanding them is necessary to use Hydra safely:

• Node roles gate who may edit source. A machine is a developer-node, production-head, worker-only, or mobile-operator (scripts/hydra-node-role.sh). Only a developer-node may make source fixes locally.
• HYDRA_HOME (runtime) is not the workshop (source). HYDRA_HOME is the live operational installation — active queues, reports, dispatch state. Hydra's own source, tests, and docs are developed, committed, and pushed from a separate HYDRA_REPO_FUTURES/workshop checkout, then pulled back into the runtime. The two directories are never the same one. See Hydra Layout and Runtime vs. Version.
• The process queue is protected state, not a suggestion. process/ (tasks/todo/, tasks/doing/, tasks/done/, tasks/blocked/) is lifecycle state. The folder a task file lives in is its state; it is not rewritten out of band by workers.
• Tasks are explicit contracts. Every task file must conform to docs/TICKET_SCHEMA.md and pass scripts/validate_task.sh, including a stated permission range — the specific paths and commands a worker may use. Unscoped or ambient access is rejected, not assumed.
• Dependency scheduling is enforced, not advisory. A task's Depends-On: list is checked before selection; the scheduler will not pick a task whose dependency is missing, waiting, or blocked.
• Permission ranges are per-task. A worker's read/write/command grants come from the task it is currently executing, not from a standing role — this README was itself written under one such grant.
• Output-Repo: is an apply target, never a review target. A task names where its changes land; a separate Review-Target-Repo:, when present, is inspection-only. The two are not interchangeable.
• Worker/model routing is manifest- and registry-driven, not a fixed assignment — the same task can route to a different worker or model depending on live worker health and capability.
• Feature-state labels are load-bearing. Docs in this repository mark claims Current, Planned/partial, Historical, or Unsubstantiated (see Terminology). Treat an unlabeled or differently-labeled claim you run into as a documentation bug to report, not as license to assume more is implemented than is stated.

How Merlin fits

Merlin (lib/Hydra/Merlin.pm, bin/hydra-merlin) is a Hydra component, not a separate product or an independent agent. It depends on Hydra's own layout and process state, and it enforces the rule that the Hydra runtime is never a workbench: fixes happen in the source checkout, are committed and pushed, and the runtime is fast-forwarded. Phase 1 is read-only diagnostics — it reads queue, incident, pause, lock, watchdog, and worker-history evidence and emits a local health snapshot. Phase 2 apply/healing (for example, requeuing an explicitly stale blocked task) is dry-run by default; even with --apply, it is gated behind operator.pause, the absence of an active doing task, no scheduler/runner lock, a clean process repo, and passing task validation. The narrow scheduler-owned exception is a matching TARGET_REPO_DIRTY_BEFORE_WORKER incident where the blocked task's latest report names a target checkout that is now clean; Merlin may then clear that one incident marker and requeue that exact task under the scheduler lease. It does not bypass or replace scheduler ownership of task selection.

How Parlay fits

Parlay is a separate, incomplete/experimental pilot and is not required to operate Hydra — see the Public Alpha Status Parlay section. It is the pilot/motivating example for project-owned process repositories (task dependency resolution across Heads): that architecture is decided, but the full resolver/lease/certificate model it exercises is not complete. Parlay's own strategy docs separately describe a longer-term human deliberation/interface role built on Hydra's Head Conversation Room Protocol; that protocol is an unimplemented design (no code backs it yet), not current Hydra behavior. For current operator interaction, use the Operator Guide and First Useful Run.

Where a new tester should start

1. Public Alpha Status — the sourced maturity statement referenced throughout this page.
2. Getting Started for External Alpha Testers — the primary step-by-step path for a technical tester with repository access: install checks, the source/runtime split, node roles, turning an idea into a validated task, running one task, inspecting the result, and stopping safely.
3. Install — the Quick Install section below, or the full Install Guide / DIY Install Guide, for install-only detail beyond what step 2 covers.
4. First Useful Run — the first meaningful task loop for an operator initializing their own local instance, as opposed to a tester using an existing shared runtime.
5. Operator Guide — day-to-day operator interaction with the task queue.
6. Terminology — look up any term used above or in other docs.
7. docs/DOCS_INDEX.md — the full documentation map, including Concepts, Operations, Security, Examples, and advanced/internal Reference material once you are past first contact.

Quick Install

Bootstrap one-liner, for the fast private-alpha path. This requires git access to git.rpdo.net:

HYDRA_REPO_URL='ssh://git@git.rpdo.net/rpdo-net/hydra-orchestrator.git' sh -c 'tmp=$(mktemp -d) && git clone --depth 1 "$HYDRA_REPO_URL" "$tmp/hydra-bootstrap" && sh "$tmp/hydra-bootstrap/bootstrap/install.sh" --skip-pull --yes'

Preferred if you want to inspect before running:

HYDRA_REPO_URL='ssh://git@git.rpdo.net/rpdo-net/hydra-orchestrator.git'
tmp=$(mktemp -d)
git clone --depth 1 "$HYDRA_REPO_URL" "$tmp/hydra-bootstrap"
cat "$tmp/hydra-bootstrap/bootstrap/install.sh"
sh "$tmp/hydra-bootstrap/bootstrap/install.sh" --skip-pull --yes

The bootstrap installer clones or updates Hydra Orchestrator under $HOME/.local/share/hydra-orchestrator by default and then delegates to the repo-local install.sh. Set HYDRA_HOME to choose another install path.

For a new local alpha test installation:

git clone https://git.rpdo.net/rpdo-net/hydra-orchestrator.git
cd hydra-orchestrator
bash install.sh --skip-pull --yes
bin/hydra-ticket doctor
bash scripts/autopilot_status.sh --short

install.sh creates the protected local runtime skeleton (tasks/, process/, recovery/) if it is missing and then attempts local worker setup. If no local AI backend is available yet, the core install can still complete with warnings.

For the first meaningful task loop, follow First Useful Run. For the full installer walkthrough, see Install Guide and DIY Install Guide.

Documentation

• Install Guide
• Public Alpha Status
• First Useful Run
• Operator Guide
• Public Alpha Readiness
• Worker Onboarding
• Terminology
• docs/DOCS_INDEX.md — full documentation map
• CONTRIBUTING_ALPHA.md
• SYSTEM_AS_IS — historical/obsolete: this document describes Hydra as "a distributed computing platform designed for scalability and reliability," which contradicts the current local-first alpha positioning above and in Public Alpha Readiness. Do not use it as a current architecture reference; see the DOC-01 source-of-truth audit and the DOC-03 truthfulness audit.

Contributing

To contribute, please read the CONTRIBUTING_ALPHA.md guide.