Hooks

Hooks are executable shell scripts that perform the actual work of deploying, health-checking, rolling back, streaming logs, and cleaning up services.

Hook directory

- - - - deploy.sh
      - health.sh
      - rollback.sh
      - logs.sh
      - cleanup.sh

All hooks are generated by muster setup from stack-specific templates. You can edit them freely after setup.

Hook types

Name	Type	Description
`deploy.sh`	hook	hookBuild and deploy the service. Called by `muster deploy`.
`health.sh`	hook	hookVerify the service is healthy. Called by `muster deploy`, `muster status`, and `muster dev`.
`rollback.sh`	hook	hookRevert to the previous version. Called by `muster rollback` and deploy failure recovery.
`logs.sh`	hook	hookStream or tail service logs. Called by `muster logs <service>`.
`cleanup.sh`	hook	hookStop processes, remove containers. Called by `muster cleanup` and `muster dev` (Ctrl+C).

Note

Exit codes: 0 = success, non-zero = failure. A non-zero exit from deploy or rollback hooks triggers the recovery menu.

Justfile alternative

Hooks can also be defined as recipes in a justfile with matching recipe names (deploy, health, rollback, logs, cleanup). Supported for both local and remote execution.

Environment variables

Muster injects environment variables into every hook execution. The variables available depend on the service configuration and project context.

General variables

Name	Type	Description
`MUSTER_SERVICE_NAME`	string	stringDisplay name of the service.
`MUSTER_DEPLOY_STATUS`	string	stringDeploy outcome: `success`, `failed`, or `skipped`. Available in post-deploy hooks only.
`MUSTER_DEPLOY_TIMEOUT`	number	numberTimeout in seconds for the deploy operation. Default: `120`
`MUSTER_DEPLOY_MODE`	string	stringPer-service deploy mode, if configured in muster.json.
`MUSTER_PROJECT_DIR`	string	stringAbsolute path to the project root.
`MUSTER_CONFIG_FILE`	string	stringPath to the muster.json configuration file.

Kubernetes variables

Available when a service has Kubernetes configuration in muster.json.

Name	Type	Description
`MUSTER_K8S_DEPLOYMENT`	string	stringKubernetes deployment name (e.g. `myapp-api`).
`MUSTER_K8S_NAMESPACE`	string	stringKubernetes namespace (e.g. `production`).
`MUSTER_K8S_SERVICE`	string	stringService key with underscores converted to hyphens (e.g. `api-v1`).

Credential variables

When credentials.enabled is true in your service configuration, muster exposes one variable per entry in credentials.required[], uppercased and prefixed:

bash

MUSTER_CRED_<KEY>   # one per entry in credentials.required[], uppercased

Credential modes control how values are persisted:

off — Credentials disabled.
save — Stored in the OS keychain.
session — Held in memory for the current session.
always — Prompted every time the hook runs.

Warning

Credentials are never stored in muster.json or committed to git.

Git variables

Available when the project is inside a git repository.

Name	Type	Description
`MUSTER_GIT_COMMIT`	string	stringCurrent HEAD SHA.
`MUSTER_GIT_PREV_COMMIT`	string	stringSHA of the last successful deploy.
`MUSTER_GIT_COMMIT_COUNT`	number	numberNumber of commits between the previous deploy and the current HEAD.
`MUSTER_GIT_DIFF_SUMMARY`	string	stringShort diff stat summarizing changes since the last deploy.

.env auto-loading

If a .env file exists in the project root, muster automatically loads it before running deploy, rollback, and dev hooks. Variables are exported without overriding existing environment variables.

When you run muster setup, hooks are generated from templates tailored to each stack type. Infrastructure services get specialized pull-only templates that skip docker build and use pull/restart instead.

Available stacks

Name	Type	Description
`k8s`	stack	stackKubernetes: `kubectl apply`, `kubectl rollout`, image tagging.
`compose`	stack	stackDocker Compose: `docker compose up`, `docker compose pull`.
`docker`	stack	stackPlain Docker: `docker build`, `docker run`.
`bare`	stack	stackGeneric shell commands, systemd restart. No container runtime required.
`dev`	stack	stackPID-managed background processes for local development.
`just`	stack	stackJustfile recipe-based hooks. Muster calls just deploy, just health, etc.

Hook security

Muster includes two layers of protection to prevent hooks from executing dangerous or tampered commands.

Dangerous command scanning

Before running deploy hooks, muster scans for dangerous patterns. If any are detected, the deploy is blocked.

text

Blocked patterns:
  rm -rf /
  mkfs
  dd if=
  curl | bash
  wget | sh
  chmod 777
  nc -l / ncat -l

Warning

If muster detects any of these patterns in your hook scripts, the deploy will be blocked with an error. Remove or refactor the offending commands to proceed.

Manifest integrity

When muster setup generates hooks, it also creates a signed manifest at .muster/hooks/hooks.manifest. This manifest contains SHA-256 hashes of all hook files, HMAC-signed with a machine-local key stored at ~/.muster/.hook_signing_key.

Before each deploy, muster verifies the manifest signature and compares file hashes. If verification fails — because a hook was modified outside of normal editing or the manifest was tampered with — the deploy is blocked.

Tip

After intentionally editing hooks, run muster hooks approve to re-sign the manifest with the new file hashes.

Overview Health Checks