Skip to content

Horae logo

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 variable HORAE_ACT_KEY works too, but horae doctor warns: 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 stops horae serve from starting;
  • set http.public_url in horae.yaml (https://horae.example.org, no path) and add its host to HORAE_ALLOWED_HOSTS;
  • have exactly one act entry with mode: tasks across 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 (on https by 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 run horae run daily-brief and horae 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/, on 127.0.0.1 only, 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 init writes a copy of it). tests/test_e2e.py runs it end to end with real plugin subprocesses, and tests/test_cli_e2e.py through the CLI.
  • Built-in example plugins (horae.plugins.builtin): fixture-source, deterministic synthetic data from a JSON fixture file, and file-sink, notes in a local vault, the core computing every note's bytes. They are small stdio MCP servers built with the mcp SDK, 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-uv cache-python). uv is pinned to an exact version in the workflow (UV_VERSION) and [tool.uv] required-version in pyproject.toml sets the minimum for local use. UV_LOCKED=1 makes every uv command fail if uv.lock is out of date.
  • The coverage gate is fail_under in [tool.coverage.report] of pyproject.toml (85); change it there.
  • Actions are pinned to commit SHAs. Renovate keeps them current, and also bumps UV_VERSION and GITLEAKS_VERSION through regex custom managers (the # renovate: marker comments in the workflow).
  • Bumping gitleaks: Renovate only updates the version. In the Renovate PR, update GITLEAKS_SHA256 by hand with the gitleaks_<version>_linux_x64.tar.gz entry of the upstream gitleaks_<version>_checksums.txt release 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 .gitleaksignore at 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.

License

Apache-2.0