Hook runtime API

Python/Bun scripts reach maand through an in-process HTTP API on the CLI host. For when to use hooks and event names, see cli/hooks.md.

Execution model

Open DB + kv.Initialize
StartRuntimeAPI (HTTP on localhost:8080 in maand process)
Resolve worker set for the event (active, allocated, rollout batch, or filtered)
Resolve rollout order (rollout_order KV when valid, else catalog order)
Split workers into batches (max_concurrent_upgrades, or max_concurrent_starts for first-start hooks)
For each batch (sequential):
  For each allocation in the batch (parallel within batch):
    Stage tmp/workers/<ip>/jobs/<job>/ from job_files + certs from KV
    Run script on CLI host via bash (python3 or bun)
    Script reaches API at HOOK_API_HOST=127.0.0.1
Commit (CLI path) or return error to caller (deploy / health_check)

Important details:

• Where code runs: bash on the CLI host, working directory = bucket root. Output is logged to structured lines in logs/<worker_ip>.log (or logs/maand.log for bucket-local). Each line includes timestamp, run id, command phase, and payload. Per-run copies live under logs/runs/<run_id>/.
• Per-allocation context: one process per allocation; env vars identify worker IP and allocation UUID even though the process is local.
• Worker access: use Python run_ssh, run_runner_target, or run_make_target to execute on ALLOCATION_IP. Bun scripts must shell out to ssh themselves or call a Python helper.
• Staging: tmp/workers/<ip>/jobs/<job>/ mirrors deploy layout (files + certs) so scripts can read local copies if needed.
• Batching: every hook event uses the same rollout order and batch width rules (see below). Batches run one after another; allocations inside a batch run in parallel.

Environment variables (hook scripts)

Per allocation

Target version is job-level KV maand/job/<job>/version and env NEW_VERSION. Running vs target for rollout logic lives in the catalog (hash.current_version, allocations.new_version) and template fields .CurrentVersion / .NewVersion.

Per batch

Every hook invocation also receives batch context for the current wave:

JOB is set on every script; batch hooks set it again alongside the batch vars above.

Event-specific

Batching

Worker order comes from rollout_order in KV when the list matches the current worker set; otherwise maand uses catalog order. Override order in pre_deploy or cli with put_rollout_order() — see kv/namespaces.md.

Batch width comes from the job manifest:

Manifest health_check probes (tcp / http / ssh) run on active allocations only, in rollout order with max_concurrent_upgrades batch width. Probes are internal maand checks — they do not run user scripts and do not receive batch env vars. health_check commands use non-removed allocations (includes disabled) with the same order and batch width.

Within a batch, all allocations (and all probe checks × workers in that batch) run in parallel. The next batch starts only after the current batch succeeds.

Use acquire_semaphore when parallel allocations must serialize a critical section (migrations, rate-limited APIs). Failures aggregate into a run error listing per-worker errors.

For a single batch run (BATCH_INDEX=0, BATCH_COUNT=1), see guides/hook-one-shot.md. For run-once logic inside a hook script, use is_one_shot() / isOneShot() — see hook-one-shot.md#guard-in-the-script.

Runtime HTTP API

Started by hooks.StartRuntimeAPI(tx) for the lifetime of build/deploy/health_check/hook sessions.

Embedded maand.py / maand.ts set these headers automatically from env vars.

Endpoint summary

KV read vs write

Writes to other maand/* keys, vars/bucket/*, and upstream jobs are rejected. Use put_rollout_order / putRolloutOrder (or PUT /kv on maand/job/<job> + key rollout_order) to override rollout order for one deploy; build resets it on the next maand build.

PUT rollout_order body:

{
  "namespace": "maand/job/api",
  "key": "rollout_order",
  "value": "10.0.0.2,10.0.0.1"
}

from maand import put_rollout_order

put_rollout_order(["10.0.0.2", "10.0.0.1"]).raise_for_status()

GET /kv body:

{ "namespace": "vars/job/api", "key": "db_url" }

Response (200):

{ "namespace": "vars/job/api", "key": "db_url", "value": "postgres://..." }

PUT /kv body (value required; optional ttl in seconds, 0 = no expiry):

{ "namespace": "vars/job/api", "key": "db_url", "value": "postgres://...", "ttl": 3600 }

PUT /kv/secret body (optional ttl in seconds):

{ "namespace": "secrets/job/api", "key": "db_password", "value": "plain-text-secret", "ttl": 86400 }

Values are encrypted with AES-256-GCM using secrets/kv.key before storage in maand.db. Expired keys are tombstoned on maand build; maand gc purges tombstones per --retain-days — see kv/persistence.md.

DELETE /kv and /kv/secret use the same JSON body as GET (namespace + key; no value).

GET /kv/keys — optional body { "namespace": "vars/job/api" }. Omit namespace to list both vars/job/<job> and secrets/job/<job> (secret listing returns key names only, never values).

KV writes during health_check

PUT, DELETE, and /kv/secret writes are rejected when the EVENT header is health_check. Health check scripts must be read-only with respect to KV — use pre_deploy or post_deploy to create or update vars and secrets.

GET /demands

Returns hooks whose manifest demands point at this job and this command name (reverse dependency lookup).

Response (200) — array of:

{
  "job": "api",
  "hook": "hook_migrate",
  "demand_config": { "min_version": "2.0.0" }
}

When to use: a shared upstream command (e.g. hook_schema on database) can inspect who depends on it and tailor behavior using demand_config (feature flags, schema versions, etc.).

Semaphores

Coordinate cross-allocation locks inside one hook session. Scoped by job + EVENT + name — the same name under pre_deploy and post_deploy are independent semaphores.

POST /semaphore/acquire body:

{ "name": "migration", "capacity": 1, "timeout_seconds": 600 }

Response (200):

{
  "name": "migration",
  "allocation_id": "<uuid>",
  "capacity": 1,
  "acquired": true
}

POST /semaphore/release body: { "name": "migration" }

GET /semaphore/status?name=migration response:

{
  "name": "migration",
  "capacity": 1,
  "holders": ["<allocation-uuid>"],
  "waiting": 0,
  "available": 0
}

When to use semaphores:

Always release_semaphore in a finally / try/finally block so a failed script does not hold the lock for the rest of the deploy session.

Example (Python):

from maand import acquire_semaphore, release_semaphore, allocation_ip

acquire_semaphore("migrate", capacity=1, timeout_seconds=900).raise_for_status()
try:
    run_migration_for(allocation_ip())
finally:
    release_semaphore("migrate")

Semaphores exist only in memory for the current maand process session — they do not survive CLI restart.

Python and Bun helpers

Embedded maand.py / maand.ts wrap the HTTP API. Prefer these over raw HTTP.

Context (env)

Aliases: get_allocation_id, get_job, kv_get, etc. (both runtimes).

KV

Demands and semaphores

Worker SSH (Python only)

Bun scripts that need SSH should invoke ssh directly or call a thin Python wrapper script.

Python virtualenv (recommended)

Create a venv per job under _hooks (not copied into tmp/ during runs; maand calls the workspace interpreter):

cd workspace/jobs/<job>/_hooks
python3 -m venv .venv
source .venv/bin/activate   # optional for manual work
pip install -r requirements.txt
pip install requests        # required if scripts use maand.py

Maand uses, in order:

1. workspace/jobs/<job>/_hooks/.venv/bin/python3
2. workspace/jobs/<job>/_hooks/venv/bin/python3
3. python3 on your PATH

.venv, venv, node_modules, and __pycache__ are skipped during maand build file indexing.

Bun

Install Bun on the CLI host. Per job:

cd workspace/jobs/<job>/_hooks
bun install

KV persistence by context

Use pre_deploy to write secrets consumed by .tpl on the same deploy. Full persistence and purge rules: kv/persistence.md. Namespace keys: kv/namespaces.md.

HTTP API errors

Check logs/<worker_ip>.log and CLI output when --verbose is set.

Related

• cli/hooks.md — events, patterns, checklist
• kv/namespaces.md · kv/persistence.md
• cli/build.md · cli/deploy.md