Maand documentation

Maand is an agentless workload orchestrator. State lives in a local bucket (maand.db, KV, secrets, staged files). Workers are reached over SSH from the CLI host; hooks run on the host with python3 and bun.

Official site: maand.sh

How this documentation is organized

Tier	Purpose	Start here
Start	Guided tour (Linux/K8s background → every feature) and first deploy	start/README.md
Guides	Task-oriented how-tos	guides/README.md
Reference	Schemas, CLI, KV, configuration	reference/README.md

Each topic has one canonical page. Other files summarize and link — they do not repeat full schemas.

Typical workflow

maand init → edit workspace → maand build → maand deploy → health_check / job ops → gc

Bucket layout

./                          # bucket root (run all maand commands here)
├── maand.conf              # SSH, certs, job_config_selector, log_format
├── data/maand.db
├── workspace/
│   ├── workers.json
│   ├── disabled.json       # optional
│   ├── bucket.conf
│   ├── bucket.jobs.conf    # optional; or bucket.jobs.<env>.conf
│   └── jobs/<job>/
│       ├── manifest.json
│       ├── Makefile        # or Makefile.tpl
│       ├── _hooks/
│       ├── _prometheus/    # optional
│       └── *.tpl
├── secrets/
├── tmp/
└── logs/                   # structured command logs; logs/runs/<run_id>/

Reader paths

Goal	Path
Learn maand from scratch	start/README.md (chapters 1–12) → quickstart
First deploy only	quickstart
Glossary	concepts
Memory / CPU / environments	resources-and-placement → configuration
Rolling cluster upgrade	rolling-deploy → manifest
Multi-job deploy order	deployment-sequence → deploy
Deploy failed or skipped	debugging-deploy → logging
Push config without restart	deploy — applying changes — `restart_policy: reload`, `restart_globs`, `--sync-only`
Disable / drain	disable-and-drain
Job hooks (Python/Bun)	hooks-tutorial → hooks
Prometheus integration	prometheus
Compare to other tools	comparison-orchestrators

Inspect state

maand info
maand cat workers
maand cat jobs
maand cat allocations
maand cat deployments
maand cat certs
maand cat kv get maand/job/<job> version
maand logs show --job <job> --format human

Local integration tests

Integration tests use real workers and local assets/ setup in the private development repository (not published here).