# Hal Guide

> Guide to the cardano-foundation/hal repository — the Cardano Foundation High Assurance Lab (HAL) team repo. Load when asked about the HAL team, its handbook, processes, weekly or monthly meeting notes, the projects table (cardano-wallet, cardano-addresses, moog, mpfs, amaru, vrf, kes, pop), ZKP/cryptography learning material, or the team's preprod infrastructure - the MPFS Docker Compose stack (cardano-node, Ogmios, Yaci Store, PostgreSQL), Moog agent/oracle deployments, Gatus monitoring, Telegram alerting, node-currency-check.sh, bootstrap.sh, Mithril snapshot bootstrap, files under infrastructure/ or docs/, or hosts 10.1.21.19/20/21.

- Skill: `cardano-foundation/hal-guide` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cardano-foundation/hal-guide`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cardano-foundation/hal-guide/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: cardano-foundation (https://skillmd.com/u/cardano-foundation)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cardano-foundation/hal-guide

---


# HAL repository guide

## Repository map

| Path | Purpose |
|------|---------|
| `README.md` | Entry point: what the repo is, projects table with statuses and versions, architecture diagram |
| `docs/handbook.md` | How the team works: organisation, stack, git workflow, testing, open improvement topics |
| `docs/weekly/`, `docs/monthly/` | Meeting notes (one file per week) and monthly reports |
| `docs/async.md`, `docs/interviews.md`, `docs/2025-09-team-workshop.md` | Process documents and retrospectives |
| `docs/radicle.md` | Radicle evaluation; ends with the November 2025 decision to stop using it |
| `docs/homebrew.md` | How to add formulae to the team's Homebrew tap (notunrandom/homebrew-cardano) |
| `docs/crypto/` | ZKP learning material: gitbook.md (SageMath/Rust/Zig exercises), journal.md, training slides |
| `docs/deployment/anti-services.md` | Historical: pre-rename Moog ("anti") deployment; superseded by `infrastructure/moog/` |
| `infrastructure/mpfs/` | Preprod MPFS compose stack: cardano-node, Ogmios, Yaci Store + PostgreSQL, MPFS, autoheal |
| `infrastructure/moog/{agent,oracle}/` | Moog agent and oracle compose files, pinned to released images |
| `infrastructure/gatus/{mpfs,agent,oracle}/` | Per-host Gatus monitoring configs with Telegram alerting |
| `infrastructure/scripts/node-currency-check.sh` | Cron script alerting when a running cardano-node image lags the latest release |
| `templates/README.md` | README template for new HAL projects |

## Build, test, run

Nothing builds or runs locally; there is no CI, no flake, no test suite. The only executable content is the deployment configuration, which runs on three CF preprod hosts from a `/opt/hal` checkout:

- MPFS host (10.1.21.21): `cd /opt/hal/infrastructure/mpfs && docker compose up -d` (after the Mithril bootstrap and secret files described in `infrastructure/mpfs/README.md`)
- Agent host (10.1.21.20): `cd /opt/hal/infrastructure/moog/agent && docker compose up -d`
- Oracle host (10.1.21.19): `cd /opt/hal/infrastructure/moog/oracle && docker compose up -d`

Do not run these on a development machine: they mount host paths (`/opt/mpfs/...`) and secret files (`/home/paolino/secrets/...`) that only exist on those hosts.

## Navigating the code

- For deployment facts (image versions, ports, networks, secrets paths), the compose files are the source of truth: `infrastructure/mpfs/docker-compose.yml`, `infrastructure/moog/*/docker-compose.yaml`, `infrastructure/gatus/*/docker-compose.yaml`.
- Yaci Store indexer settings (sync start slot, enabled stores, Ogmios URL) are in `infrastructure/mpfs/application.properties`.
- Monitoring conditions (what fires a Telegram alert) are in `infrastructure/gatus/*/config.yaml`.
- The node config files in `infrastructure/mpfs/configs/` come from book.play.dev.cardano.org; `configs/download.sh` refreshes them.
- Team decisions and their history live in `docs/` (handbook for current practice, weekly/monthly notes for when something changed).

## Using the artifacts

This repo is consumed by reading, not installing. Typical operations:

- Deploy or update a service: follow the README next to its compose file (`infrastructure/{mpfs,moog/agent,moog/oracle}/README.md`); always `docker compose` from the `/opt/hal` checkout directory.
- Bootstrap a fresh MPFS node database: `source infrastructure/mpfs/bootstrap.sh` (requires a local `.env` defining `MPFS_DIR`; downloads a Mithril preprod snapshot).
- Check monitoring: Gatus web UI on the MPFS host listens on port 8090; alerts go to Telegram.
- Test the currency check without sending alerts: `DRY_RUN=1 infrastructure/scripts/node-currency-check.sh <telegram-env-file>`.

## Answering questions

- "What does the HAL team work on?" → the Projects table in `README.md` (status icons + pinned versions; verify versions against GitHub releases before quoting them, they age).
- "How does the team work / what's the process?" → `docs/handbook.md`; open questions are in its WIP section and in `docs/interviews.md`.
- "What runs in preprod / what is deployed where?" → `infrastructure/README.md` (host table + architecture diagram), then the per-service compose files.
- "Why did an alert fire?" → `infrastructure/gatus/*/config.yaml` for the condition; `infrastructure/scripts/node-currency-check.sh` for release-lag warnings.
- "What is MPFS / Moog?" → one-liners in the Projects table; the real docs are in their own repos (cardano-foundation/mpfs, cardano-foundation/moog).
- "Did the team adopt Radicle?" → no; `docs/radicle.md`, November 2025 decision.