Configuration fields

This reference describes v4.2.4. Use Environment and secrets and Lifecycle for workflows. Fields below come from the version-pinned schema and readers, not a newer checkout.

Project JSONCopy Anchor Link

The legacy project file is .hack/hack.config.json. Requiredness below is relative to the containing schema object or union variant. An optional parent does not become required because a child is required. Repeated paths describe different variants. The schema requires name and dev_host; the reader has compatibility fallbacks. A schema constraint is not proof the reader validates it. No schema default is declared for these fields.

Aliases and selectionCopy Anchor Link

Prefer env.defaultOverlay for the default overlay. The reader checks env.defaultOverlay before env.default_overlay; nested env selection precedes legacy defaultEnvConfig, which in turn precedes default_env_config. These nested fields are read even though the legacy generated schema does not enumerate the env object. worktree.autoBranch is an alias of worktree.auto_branch; a non-null snake_case value is selected before the camelCase alias, then parsed as a boolean. Use one spelling rather than conflicting aliases.

Effective fallbacksCopy Anchor Link

Log preferences are not forced backend selection. Follow mode prefers Compose; snapshots prefer Loki, with consumer-specific fallback. startup[].persistent defaults false. Linked-worktree auto-branch selection defaults on in the legacy Compose path; an ordinary checkout remains the base instance. Follow the runtime-specific command guide.

Hooks and processesCopy Anchor Link

startup accepts string shorthand or objects. Startup objects require at least one of run or command. The reader prefers run and drops entries whose selected command is empty. They accept optional name/cwd, and persistent (false by default). lifecycle.up.before/after and lifecycle.down.before/after are hook arrays; their command-object variants require command. Do not transfer the startup-only run spelling to every hook. lifecycle.processes names long-lived processes and requires name and command. singleton.ports contains unique positive ports; singleton.onConflict selects adopt or fail. Read Lifecycle for working-directory origins, ordering, ownership and failure behavior.

Scope exclusionsCopy Anchor Link

Retained gateway, cluster, supervisor, shared/broker ownership and extension-manager fields are not a supported hosted product API. Legacy secret-backend strategy fields are separate from the managed YAML format below. Neither permissive unknown keys nor a retained schema field makes a backend qualified. Internal daemon, guest and compiler transport types are not public API specifications.

Managed environment YAMLCopy Anchor Link

Files such as .hack/hack.env.default.yaml use values, not the older JSON vars format. Use hack env to manage values and Share environment and secrets for key handling. Examples must use placeholders, never real secret values.

version: 1, secretsprovider: project_key, and an object values are required. Each scope is an object. Scope names match ^[a-z0-9][a-z0-9._-]*$; keys match ^[A-Z_][A-Z0-9_]*$. Missing values.global becomes an empty object. The environment falls back to the selected layer; an example containing environment: default does not establish a universal default. Secure values require a nonempty secure string; valid shape alone does not prove decryption or key availability.

This version rejects YAML null values. Do not copy null-removal examples from v5.

The parser selects recognized fields; this is not a closed JSON-schema promise. The legacy hack.env.json schema describes a different file format.

Branch registryCopy Anchor Link

.hack/hack.branches.json records CLI-managed branch metadata, not live container ownership. Use branch commands rather than hand-editing runtime directories.

name is the human/Git branch name; slug is its runtime-safe identifier. note is an annotation. Usage updates fill a missing created_at and refresh last_used_at; neither timestamp proves a running instance or permits deleting data. A missing registry starts empty. Invalid JSON is reported. The parser drops invalid entries and narrows recognized fields, so it does not enforce every schema pattern/date format/unknown-key constraint.

---

Source: v4.2.4 · docs/site/reference/configuration-fields.md.