Quick start¶
Three ways in, from the quickest to the one you would keep running:
- Try it from a checkout (no Docker, no secret, no network): a first pipeline, its dry run, undo and replay.
- Docker Compose: the container image on a machine with Docker, API on loopback.
- Coolify: the reference deployment, behind Traefik and SSO.
Provisional
Horae is pre-release and its decisions are provisional. The image tag in the deploy
templates is bumped by hand, and anything that says "planned" is not on main yet.
Try it from a checkout¶
You need git and uv (it installs
Python 3.12 itself).
git clone https://github.com/horae-dev/horae.git
cd horae
uv sync
uv run horae init ~/horae-demo
uv run horae doctor -i ~/horae-demo
uv run horae run daily-fixture -i ~/horae-demo --dry-run
uv run horae run daily-fixture -i ~/horae-demo
uv run horae runs -i ~/horae-demo
doctor prints OK: 1 pipeline, 2 plugins, 0 model aliases. The dry run shows the note the
pipeline would write and writes nothing; the real run writes
~/horae-demo/vault/Daily/<today>.assistant.md. horae runs lists both runs, the dry run
marked (dry run). Undo the real one, using its id from the first column:
uv run horae undo <run-id> -i ~/horae-demo
Undo reverses what the run did: here it removes the note, because the run created it (a note that existed is restored byte for byte). This example has no LLM and reads synthetic data; the concepts page explains what ran.
Docker Compose¶
The template is deploy/compose/:
Horae alone, on 127.0.0.1, with a read-only root filesystem, a named volume for the
instance and the built-in scheduler. You need Docker with the Compose plugin.
1. Check that the image can be pulled¶
The templates pull ghcr.io/horae-dev/horae
without credentials, which works only when its package is public:
curl -s -o /dev/null -w '%{http_code}\n' \
'https://ghcr.io/token?scope=repository:horae-dev/horae:pull'
200 means public: use step 2a. 401 means it is not (yet): use
step 2b.
2a. Pull the image¶
git clone https://github.com/horae-dev/horae.git
cd horae/deploy/compose
cp .env.example .env
mkdir -p secrets
docker compose up -d
2b. Build the image from the checkout¶
git clone https://github.com/horae-dev/horae.git
cd horae
docker build -t horae:local .
cd deploy/compose
cp .env.example .env
mkdir -p secrets
cat > local.yaml <<'EOF'
services:
horae-init: {image: "horae:local"}
horae: {image: "horae:local"}
EOF
export COMPOSE_FILE=docker-compose.yaml:local.yaml
docker compose up -d
3. Check it¶
docker compose ps -a
curl -s http://127.0.0.1:8080/healthz
docker compose exec horae horae doctor
docker compose exec horae horae run daily-fixture --dry-run
horae is Up (healthy) and horae-init is Exited (0) (it created the example instance
in the volume). /healthz answers {"status": "ok", ...}.
If curl on the host gets an empty reply (seen with OrbStack on macOS, whose port forwarding
differs from Docker on Linux), the container is still fine: check it from inside with
docker compose exec horae horae doctor.
Next:
- Put your own
horae.yaml,pipelines/andhorae.lockin the volume, and secrets as files insecrets/(one file per secret): Docker Compose guide. - The API has no authentication of its own. The template binds it to loopback on purpose; never publish it on another interface. For a public host use the Traefik and SSO override described in the guide.
- Pin the image by digest in production, and back up the volume: container image, backups.
Coolify¶
deploy/coolify/docker-compose.yaml
is a Coolify Docker Compose Empty resource with its own Traefik routers, an SSO
forwardAuth middleware, and only /act/ exempt from SSO. Before you start you need a Coolify
server with its Traefik proxy, an SSO provider (authentik is the reference) configured as
described in the Coolify guide, a DNS
name such as horae.example.org pointing at the server (or a Cloudflare Tunnel), an Anthropic
API key and two Uptime Kuma push URLs.
- In your project: + New, Resource, Docker Compose Empty. Paste the template and save.
- Edit Compose and turn off "Escape special characters in labels".
- Leave the Domains of both services empty (a Coolify domain would create routers without SSO).
- In Environment Variables, set the four required ones. Coolify blocks the deployment until you do:
| Variable | Example value |
|---|---|
HORAE_PUBLIC_HOST |
horae.example.org |
HORAE_ANTHROPIC_API_KEY |
your key (a secret) |
HORAE_MONITOR_DAILY_BRIEF_URL |
https://kuma.example.org/api/push/<token> |
HORAE_MONITOR_REMIND_URL |
https://kuma.example.org/api/push/<token> |
On Coolify's default proxy also set HORAE_TRAEFIK_CERTRESOLVER=letsencrypt.
5. Deploy. horae shows Running (healthy) and horae-init shows Exited.
6. Open https://horae.example.org/healthz: it goes through the SSO sign-in, then answers
{"status": "ok", ...}.
7. Add your instance and the two Scheduled Tasks (horae run daily-brief,
horae run remind), and run the checks of the guide.
The guide has the rest: the Cloudflare Tunnel mode, the exact routing and why, forwarded headers, the checks to run on the server, updates and backups: Deploying Horae on Coolify.