
horae¶
Core runtime, CLI, HTTP API, MCP server, SDK and docs for Horae, a predictable self-hosted personal agent.
๐ง Planned. Nothing to install yet. Follow progress on the Horae roadmap project.
What Horae is¶
Horae is a predictable, self-hosted personal agent:
- Pipelines, not agent loops:
collect โ transform โ llm โ act โ notify, declared in YAML. - One bounded LLM step: a skill, an output schema, a model alias, a budget and no tools.
- Plugins return intents; the core applies them with a dry-run diff, a journal and
horae undo. - Declared permissions: hosts, secrets, paths and intents, approved at install and enforced at run time.
- A git marketplace: plugins pinned to a commit in
horae.lock; nothing updates itself. - Bring your own model: Anthropic API, your own
claude -p, OpenAI-compatible endpoints or Ollama.
Read the plan, the roadmap and the estimation.
Planned work¶
| Milestone | Epic |
|---|---|
| M0 Foundations | Foundations โ Repository, CI, ADRs, JSON Schemas, threat model and the agent workflow that every other epic relies on. |
| M1 Walking skeleton | Pipeline engine and plugin host โ Load an instance, run pipelines, record runs, apply intents with dry-run, journal, undo and replay; talk to plugins over MCP stdio. |
| M2 LLM step | Bounded LLM step โ Skills with output schemas, model backends (anthropic, claude-cli, openai-compatible, ollama), cache, budgets, de-identification and untrusted-content guards. |
| M3 Dogfood | Runtime and delivery โ HTTP API, signed action links, scheduler, container image, Coolify template and the plugin SDK. |
| M4 Marketplace | Marketplace client โ Install, upgrade, remove and audit plugins from git with pinned commits, per-plugin venvs and approved permissions. |
| M5 Hard isolation | Hard isolation โ Per-plugin containers, egress allow-list proxy, declared mounts, secret redaction and a malicious-plugin test suite. |
| M5 Hard isolation | Horae MCP server โ Read-only MCP tools for other agents and an approval-gated pipeline.run. |
| M8 Public v0.1 | Docs and v0.1 release โ Docs site, release automation, signed artifacts and the v0.1 release. |
| M0 Foundations | Human operations โ Tasks only a human can do: accounts, keys, GitHub App installs, server resources and device tests. |
Stories, estimates and acceptance criteria are in this repository's issues and on the roadmap project.
Getting started¶
From a checkout (uv sync; nothing is published yet), the M1 walking skeleton in a new
directory: a pipeline that reads synthetic data and writes today's owned note in the
instance's own vault/, through the two built-in plugins. No LLM, no secret, no network.
uv run horae init ~/horae-demo # horae.yaml, a pipeline, horae.lock, vault/, plugins/
uv run horae doctor -i ~/horae-demo # "OK: 1 pipeline, 2 plugins, 0 model aliases"
uv run horae run daily-fixture -i ~/horae-demo --dry-run # the diff; nothing written
uv run horae run daily-fixture -i ~/horae-demo # writes vault/Daily/<today>.assistant.md
uv run horae runs -i ~/horae-demo # runs, newest first
uv run horae diff <run-id> -i ~/horae-demo # what a stored (dry) run would change
uv run horae replay <run-id> -i ~/horae-demo # re-executes the run from its record and compares
uv run horae undo <run-id> -i ~/horae-demo # restores every note the run changed, byte for byte
uv run horae usage -i ~/horae-demo # LLM cost per pipeline and day (the usage ledger)
uv run horae cache purge --all -i ~/horae-demo # forget cached LLM outputs (the next run asks again)
uv run horae plugin search -i ~/horae-demo # plugins of the `marketplaces` in horae.yaml (cached; --offline works)
uv run horae plugin resolve github@0.2.0 -i ~/horae-demo # -> repo and pinned commit
uv run horae plugin add github@0.2.0 -i ~/horae-demo # clone, verify tag and SHA, show and approve permissions, pin in horae.lock (deps: #45)
uv run horae plugin upgrade github -i ~/horae-demo # permission diff; anything new is approved again; atomic swap
uv run horae plugin audit -i ~/horae-demo # plugins, permissions, last activity; exit 4 on drift (--json)
uv run horae plugin remove github -i ~/horae-demo # tree, venv, pack pipelines and lock entry (disable it in horae.yaml first)
uv run horae eval daily-brief/rank-and-word --plugin-dir tests/fixtures/plugins # golden cases, offline
horae plugin add shows the permissions the plugin declares and asks you to approve them
before pinning it in horae.lock. First-party plugins of the Horae marketplace run under
either runtime; any other plugin (a community tier, an index you added, a direct install)
installs and runs only in a container: set plugins.<name>.runtime: container (or
plugin_defaults.runtime: container) in horae.yaml first, with Docker available
(decision 79; how-to
in the operator guide).
--allow-host HOST and --allow-local HOST:PORT grant more (your own Home Assistant, say);
--yes re-installs, without asking, only what horae.lock already approves (a Docker build
from a committed lock). Details: schemas decision 70.
A direct install without a marketplace, horae plugin add https://<host>/<owner>/<repo>@<full
commit SHA>, has no tier, so it needs runtime: container too
(decision 71); horae plugin upgrade <same URL>@<new SHA>
moves it to another commit its branches or tags reach.
A pipeline pack (a plugin whose plugin.yaml lists provides.pipelines) also gets its
pipelines installed: pipelines/<name>.yaml of the pack is validated and copied to
<instance>/pipelines/<plugin>/<name>.yaml, and the paths are recorded in
plugins/<plugin>/.horae-install.json. The install is refused, and nothing is written, if any
file is invalid, is a symlink, or would replace a file or pipeline of yours. The approval
prompt lists each pipeline (trigger, tools, skills; a warning for tools of other plugins) and
horae.lock pins their digests; they run only once the plugin is listed under plugins: in
horae.yaml
(schemas decision 72).
horae plugin upgrade NAME[@VERSION] resolves the new version like add, installs it next to
the old one with its own venv, and shows what changes against horae.lock: a new host, local
endpoint, secret, intent, path or pack pipeline (or a changed one, or a dropped personal field)
must be approved again, and --yes passes only when nothing widens. Hosts you added are kept.
The trees are swapped and the lock rewritten only after approval; on any failure the old
version stays. A lower version needs --allow-downgrade. horae plugin remove NAME refuses a
plugin still listed under plugins: in horae.yaml, then deletes its tree, venv, lock entry
and the pack pipelines that are still its own, and lists what it kept: secrets (unless
--delete-secrets), the files it wrote and the run history. horae plugin audit lists every
plugin with its version, source, tier, permissions and last run, and reports drift between
horae.lock and the disk (exit 4), including a plugin that is not first-party but would not
run in a container
(schemas decision 73).
Plugin containers (M5, #49): with runtime: container in horae.yaml
(plugin_defaults.runtime, or plugins.<name>.runtime, which wins; the default is process)
a plugin runs in its own Docker container instead of as a child process: non-root, read-only
root filesystem, no capability, Docker's default seccomp profile, a noexec tmpfs on /tmp,
only its own directory (tree and venv) mounted read-only, and its own internal network with no
egress and no route to the host (the egress proxy is #50). Secrets reach it through stdin, never
its command line or docker inspect. If the container cannot start (no Docker, image not
pulled, a venv the image cannot run), the plugin fails with runtime_unavailable: it never
falls back to a process. Prerequisites, the Horae-in-Docker options (the published image mounts
no Docker socket), and measured latency (about 0.25 s more per plugin start, the same per call):
docs/operations/plugin-containers.md,
schemas decision 74.
-i defaults to the current directory (or HORAE_INSTANCE). Every command takes --json
for scripting (one JSON document on stdout, schema_version: 1, errors too) and prints no
colour unless asked. horae run has no LLM backend in M1: a pipeline with an llm step
fails with llm_unavailable (M2 adds the backends). SIGINT or SIGTERM stops a run
cooperatively and names it: before the apply its partial record is saved failed; once the
apply has started it finishes (each sink call is bounded by its timeout) and the record is
saved before the run is reported interrupted (a second signal is ignored).
Scheduling (decision 49). A pipeline's trigger: {cron: "30 5 * * *"}
(optional timezone, else the instance's) is run by horae serve, the long-running process
of a container, until SIGTERM (it then cancels and saves the runs in progress and exits 0;
give the container at least 20 s to stop, e.g. compose stop_grace_period: 20s). It reads
the instance once at start: restart it after changing the configuration, and it logs on
stderr (no --json). Scheduled runs run one at a time by default
(scheduler.max_concurrent). Missed fire times are not caught up, a fire time more than
scheduler.misfire_grace_s (1 h) late is skipped, and a fire time while the pipeline is
still running, here or in a manual horae run, is skipped and logged. With HORAE_SCHEDULER=external (or scheduler.mode: external) no trigger
fires: Coolify Scheduled Tasks, cron or a systemd timer call horae run <pipeline>. Either
way, scheduler.monitors.<pipeline>: {secret: PUSH_URL} pings an Uptime Kuma push URL (or
kind: healthchecks), kept as a secret, up or down after each run; a failed ping is a
warning and never fails the run.
HTTP API (decision 51). horae serve also serves a small read-only
API on --host/--port (HORAE_HOST, HORAE_PORT; 127.0.0.1:8080 by default, 0.0.0.0 in
the container image): GET /healthz (200 when the store is readable and the scheduler runs,
else 503; the store's state and the scheduler's: next and last fire times, outcomes, pings,
skips), GET /runs (newest first, as horae runs --json; limit up to 100, cursor from
next_cursor, pipeline, status, all=true for live skill evals) and GET /runs/<id>.
Every response is redacted and sent with Cache-Control: no-store and a default-src 'none'
CSP; there is no CORS and no OpenAPI page. It has no authentication of its own: expose it
only through the reverse proxy and its SSO middleware (only /act/ is exempt), never directly.
Against DNS rebinding it answers only requests whose Host is localhost, 127.0.0.1, ::1
or an --allowed-host (HORAE_ALLOWED_HOSTS, space-separated): set the proxy's public
hostname there, or every proxied request gets 400 invalid_host (horae serve warns at start
when it listens on 0.0.0.0 or :: without one, and logs each refused Host once). In a
container, change the port with HORAE_PORT rather than --port (the image's health check
follows HORAE_PORT).
Action links (decision 54). A notify.push may carry up to three
buttons (actions: [{kind: task.done | task.snooze, task, duration: 1h | 3h | tomorrow}],
for open tasks the run collected; a proposed label is ignored: the core labels the buttons
Done, Snooze 1h, Snooze 3h, Tomorrow, and a recurring task gets no Done); when it
is sent, the core mints for each a signed, single-use link <http.public_url>/act/<token>,
valid 24 hours and bound to the task's current status, due date and snooze, and passes it to
the notifier (ntfy renders it as an http button: one tap marks the task done or snoozes
it). GET /act/<token> (a browser, a
link preview) only shows a confirmation page; POST applies the change once, through the
instance's mode: tasks sink, as a run of the reserved pipeline _act. To turn it on:
- set the key, at least 32 bytes, in
<secrets.dir>/HORAE_ACT_KEY(the environment variableHORAE_ACT_KEYworks too, buthorae doctorwarns: a plugin running as the same user can read the core's environment):openssl rand -base64 48. Rotating it (a new value, then a restart) invalidates every outstanding link. A shorter key stopshorae servefrom starting; - set
http.public_urlinhorae.yaml(https://horae.example.org, no path) and add its host toHORAE_ALLOWED_HOSTS; - have exactly one
actentry withmode: tasksacross the pipelines.
Without the key /act answers 503 and notifications are sent without buttons. /act/ is the
only path the reverse proxy exempts from SSO (the #41 templates match the link's exact
shape and turn Traefik's access log off for it). Requests are rate limited (10 a minute per
client, an IPv6 client by its /64; 60 a minute overall for links whose signature verifies).
In the reference deployment (Cloudflare tunnel, then Traefik) no entry point may trust
forwarded headers (operations/coolify.md), so
Traefik replaces X-Forwarded-For with cloudflared's address and every phone shares one
bucket (still limited); http.trusted_proxies only helps behind a proxy chain that passes the
client's address on safely.
http.trusted_proxies takes networks of /8 (IPv4) or /32 (IPv6) at the widest.
An instance is not relocatable in v1: horae.lock holds the vault's absolute path and
plugins/ the absolute path of the interpreter that installed them. After copying or moving
one, horae doctor reports the paths that no longer match (a lock path that does not exist,
an own vault/ the lock does not write to, a plugin command that is not executable); fix
the lock, or run horae init in the new place.
horae doctor also checks the container-only policy for third-party plugins (decision
79): an error for each installed plugin that is not first-party (its tier,
as horae.lock records it) whose effective runtime is not container (the plugin host would
refuse to start it; horae plugin audit reports the same as runtime_not_container), and an
error when a plugin runs with runtime: container but no usable local Docker engine is
available (the CLI is missing, DOCKER_HOST or the current context is not a local unix://
socket, or the daemon does not answer). It starts and pulls nothing.
Exit codes, the same for every command (decision 37):
| Code | Meaning |
|---|---|
| 0 | ok: no problem, listed, planned, identical, undone, created |
| 1 | a configuration, store, plugin or runtime problem (doctor found problems, the run failed or timed out) |
| 2 | usage error |
| 3 | unknown or refused: unknown run or pipeline, a refused run, not comparable, a non-empty init target |
| 4 | different: the replay differs, the plan has problems, undo refused because a note changed |
| 5 | locked: the pipeline is running, or another process is applying changes |
| 70 | internal error (only its type is printed) |
| 130 / 143 | horae run interrupted by SIGINT / SIGTERM |
MCP server¶
horae mcp serve -i <instance> serves tasks.today, brief.latest and runs.recent to an MCP
client over stdio, read-only (#54). Add it to Claude Code with
claude mcp add horae -- horae mcp serve -i <instance>. Over the network, horae mcp serve
--http (loopback, port 8765 by default) requires a bearer token on every request: create one
with horae mcp token create NAME (shown once, stored hashed), connect with
claude mcp add --transport http horae http://127.0.0.1:8765/mcp --header "Authorization: Bearer
<token>", and revoke it with horae mcp token revoke NAME (#56). pipeline.run (scope
pipeline.run) only makes a dry run and returns an approval id; nothing is applied until you
run horae approval approve <id> yourself on the instance's terminal, which shows the changes
and asks you to retype a short code (#55; friction, not a barrier against an agent that also
has a shell as you). Setup, the tool schemas and the manual check are in docs/mcp.md.
Deployment¶
The container image is ghcr.io/horae-dev/horae
(docs/operations/container-image.md: tags, signatures,
the runtime contract). Two ready deployments (#41), both on a named volume for /instance, with
a read-only root filesystem and a one-off horae init on a new volume:
- Coolify (the reference deployment, PLAN ยง7):
deploy/coolify/docker-compose.yaml, a Docker Compose Empty service with its own Traefik routers (onhttpsby default, or behind a Cloudflare Tunnel as an opt-in), an authentik forwardAuth middleware of Traefik's file configuration and the resource's own network (shared only with Coolify's proxy); only/act/is exempt from SSO. Required variables block the deployment until they are set; Scheduled Tasks runhorae run daily-briefandhorae run remind, each with an Uptime Kuma push monitor. Guide (prerequisites, the tunnel's public host name, what to verify on the server): docs/operations/coolify.md. - Plain Docker Compose:
deploy/compose/, on127.0.0.1only, with an optional Traefik and SSO override; built-in scheduler or host cron. Guide: docs/operations/compose.md.
Both pull ghcr.io/horae-dev/horae without credentials, which needs the GHCR package to be
public: check first (the guides give the one-line check and the registry login otherwise).
tests/test_deploy_templates.py checks the rendered files (routing, hardening, required
variables).
Examples¶
examples/walking-skeleton: the M1 walking skeleton, an instance whose pipeline reads synthetic data and writes today's owned note, with dry run, undo and replay (horae initwrites a copy of it).tests/test_e2e.pyruns it end to end with real plugin subprocesses, andtests/test_cli_e2e.pythrough the CLI.- Built-in example plugins (
horae.plugins.builtin):fixture-source, deterministic synthetic data from a JSON fixture file, andfile-sink, notes in a local vault, the core computing every note's bytes. They are small stdio MCP servers built with themcpSDK, and a starting point for writing a plugin.
Development¶
Setup, commands, conventions and the definition of done are in AGENTS.md. Provenance trailers are added by scripts/graft_trailers.py (pre-commit prepare-commit-msg). graft.yaml is validated in tests against a vendored schema (tests/fixtures/graft.v1.schema.json, from mmornati/graft@3f40dd1).
CI¶
.github/workflows/ci.yml runs on every PR and push to main: lockfile check, ruff, mypy, pytest with coverage, gitleaks (history of the checked-out ref), CodeQL (python, actions), the image build and smoke test, and docker compose config on the deploy templates (deploy). The aggregate job CI OK (ci-ok) fails if any other job failed, was cancelled or skipped; mark it as the single required status check in branch protection.
- Python comes from
.python-version, installed by uv itself (UV_PYTHON_PREFERENCE=only-managed, cached via setup-uvcache-python). uv is pinned to an exact version in the workflow (UV_VERSION) and[tool.uv] required-versioninpyproject.tomlsets the minimum for local use.UV_LOCKED=1makes everyuvcommand fail ifuv.lockis out of date. - The coverage gate is
fail_underin[tool.coverage.report]ofpyproject.toml(85); change it there. - Actions are pinned to commit SHAs. Renovate keeps them current, and also bumps
UV_VERSIONandGITLEAKS_VERSIONthrough regex custom managers (the# renovate:marker comments in the workflow). - Bumping gitleaks: Renovate only updates the version. In the Renovate PR, update
GITLEAKS_SHA256by hand with thegitleaks_<version>_linux_x64.tar.gzentry of the upstreamgitleaks_<version>_checksums.txtrelease asset, otherwise the checksum step fails. - Historical leak: if gitleaks flags a commit that is already in history (for example a revoked, synthetic or false-positive value), first revoke the secret if it was real. Then add the finding's fingerprint, printed as
Fingerprint: <commit>:<file>:<rule>:<line>in the job output, as one line to.gitleaksignoreat the repository root, with a comment explaining why. History is not rewritten.
Contributing¶
This project is developed mostly by AI coding agents supervised by a human maintainer. Read AGENTS.md for the workflow (it applies to humans too), and the organization's contributing guide and security policy.