Core concepts

First time here? Read the guided tour (chapters 1–12) for a slower introduction. This page is a consolidated reference for bucket, worker, job, and allocation.

Maand is an agentless workload orchestrator. You run the maand CLI on a host machine (laptop, CI runner, or bastion). That host holds the bucket — local files and SQLite state. Workers are ordinary Linux hosts reached over SSH; nothing is installed on them except what you deploy (job files, runner.py, and runtime directories).

┌──────────────────── maand CLI host ────────────────────┐
│  bucket/                                               │
│    maand.db + KV    workspace/    secrets/    tmp/     │
│         │                │                             │
│         │    build reads │                             │
│         ▼                ▼                             │
│    catalog (workers, jobs, allocations)                │
└────────────────────────┬───────────────────────────────┘
                         │ ssh + rsync (deploy, job control)
         ┌───────────────┼───────────────┐
         ▼               ▼               ▼
    Worker A         Worker B         Worker C
    /opt/worker/<bucket_id>/

Official site: maand.sh

Bucket

A bucket is one maand project directory. Run all maand commands from that directory (or with bucket.Location set to it in tests).

Each bucket has a stable bucket_id (UUID) and an update_seq incremented on every deploy. Workers store both in worker.json so manual job control can detect drift.

Build reads workspace/ → updates maand.db and KV. Deploy reads the DB → rsyncs to workers. Workers are never the source of truth for catalog data.

Worker

A worker is a cluster node — an SSH target identified by IP or hostname.

Definition

Workers are declared in workspace/workers.json:

[
  {
    "host": "10.0.0.1",
    "labels": ["worker", "gpu"],
    "memory": "8192 mb",
    "cpu": "4000 mhz",
    "tags": { "zone": "a", "rack": "1" }
  }
]

On the worker after deploy

/opt/worker/<bucket_id>/
├── worker.json          # bucket_id, worker_id, update_seq, labels
├── jobs.json            # list of jobs on this worker (+ disabled flag)
├── bin/runner.py        # runs Makefile targets via SSH job control
└── jobs/<job>/          # staged job tree (Makefile, configs, data/, logs/, bin/)

Worker lifecycle

Workers do not run a maand agent. Deploy and maand job invoke runner.py over SSH; maand collect facts probes capacity into workers.json; maand run_command runs arbitrary shell commands over SSH.

Job

A job is a deployable unit — a directory under workspace/jobs/<name>/.

Required layout

workspace/jobs/api/
├── manifest.json       # version, selectors, resources, commands, certs
├── Makefile            # start / stop / restart (default deploy lifecycle)
├── _hooks/           # optional: hook_<name>.py | .ts | .js
├── config.tpl          # optional: Go templates → rendered at deploy
└── …                   # other files copied into maand.db on build

Manifest highlights

Manifest reference: manifest.md. Configuration: configuration.md. Command scripts: cli/hooks.md.

Job lifecycle on workers

Each deploy wave rsyncs the job tree, then optionally runs Makefile targets on the worker:

1. New allocation → make start
2. Upgrade → depends on restart_policy:
   • always → make restart
   • reload → make reload, or make restart when a changed file matches restart_globs
   • never → no lifecycle (files only)

The Makefile receives CURRENT_VERSION (running) and NEW_VERSION (target). Custom rollouts use a job_control command instead of the default targets.

Runtime state lives in data/, logs/, and bin/ on the worker — not in the workspace (build rejects those dirs in git).

Allocation

An allocation is the binding (job × worker): “run job api on worker 10.0.0.1.”

Maand creates allocations automatically during build by label matching:

1. For each worker, collect its labels (including worker).
2. For each job, use manifest selectors when set; otherwise use the job name as the selector.
3. Require every selector to appear on the worker.
4. Insert or update a row in allocations for each match.

workers.json              jobs/api/manifest.json
  labels: [worker,         selectors: [worker, prod]
           prod]                   │
       │                           │  selectors: [worker, prod]
       └──── all match? ───────────┘
                 │
                 ▼
        allocation (api @ 10.0.0.1)
        alloc_id = hash("api|10.0.0.1")

Dedicated jobs can omit manifest selectors when the worker carries the job name (for example job prometheus on a worker labeled prometheus).

Allocation fields

Each allocation tracks catalog current_version (last promoted, in hash) and new_version (build target, in allocations). Job-level KV maand/job/<job>/version holds the manifest target. Templates and hooks expose running vs target via .CurrentVersion / .NewVersion and CURRENT_VERSION / NEW_VERSION — see deploy.md.

Active vs inactive

An allocation is active when removed = 0 and disabled = 0. A disabled allocation (removed = 0, disabled = 1) still gets build KV (certs, per-allocation metadata, deploy staging) and hook fan-out (post_build, pre_deploy, post_deploy, health_check commands, cli). Manifest health probes skip disabled allocations. Deploy never starts disabled allocations (no start/restart/reload/rsync). Content and version changes are still staged and promoted; after re-enable, deploy starts the allocation.

KV nuance: maand/job/<job>/workers, maand/job/<job>/rollout_order, and maand/worker/<ip>/jobs list active allocations only. Per-allocation keys such as peer_workers use non-removed peers (disabled peers may still appear). See KV namespaces.

Only active allocations receive:

• Deploy rsync and lifecycle (start/restart/reload) plus rollout hooks that run on workers
• maand hooks, maand health_check
• Default targets for maand job start|stop|restart|run --target reload

Inspect allocations:

maand cat allocations
maand cat allocations --jobs api --workers 10.0.0.1

Disabling without removing

workspace/disabled.json marks allocations disabled without deleting workspace files:

{
  "jobs": {
    "api": { "allocations": ["10.0.0.2"] }
  },
  "workers": ["10.0.0.3"]
}

• Disable all instances of a job: "api": {}
• Disable one worker for a job: "allocations": ["10.0.0.2"]
• Disable every job on a worker: "workers": ["10.0.0.3"]

Run maand build after editing disabled.json.

Full how-to (disable one allocation, entire job, entire worker, re-enable): disable and drain.

How the three relate

One job typically has many allocations (one per matching worker). One worker typically hosts many jobs (one allocation per job).

Deployment sequence

Jobs that depend on each other (via demands in manifest hooks) get a deployment_seq during build. Deploy processes sequence 0, then 1, and so on — so depended-on jobs reach workers before dependents.

Full reference: deployment-sequence.md.

Details in cli/build.md and cli/deploy.md.

Hooks vs Makefile vs run_command

Hooks talk to maand’s runtime HTTP API and KV store on the CLI host. See cli/hooks.md and hook-api.md.

Typical state flow

edit workspace/workers.json, workspace/jobs/*
        │
        ▼
   maand build          ← catalog + KV + certs; no SSH to workers
        │
        ▼
   maand deploy         ← rsync + lifecycle (start/restart/reload) + hooks
        │
        ├── maand health_check
        ├── maand job restart <job>
        ├── maand hooks <cmd> [job]
        ├── maand collect facts --generate-workers > workspace/workers.json   # optional: refresh worker capacity
        ├── maand run_command "…"
        └── maand gc     ← after removals

Further reading

• overview.md — capabilities and limits
• quickstart.md — hands-on first deploy
• reference/README.md — configuration, manifest, CLI, KV, logging
• ../README.md — full doc index