The hypermake.json reference

A Hypermake project is declared by one file at the project root: hypermake.json. This page documents every key the loaders actually read — derived from the loader code, not from intent — with its type, default, and which parser reads it. This site's own hypermake.json is used as the primary worked example.

How the file is read

There is no single parser. Three read paths share the file, and they disagree about strictness. This is a real property of the current contract, so the reference states it up front and attributes every key below to its reader.

Identity and roots

{
  "id": "hypermake",
  "name": "Hypermake",
  "rootUuid": "8633838b-1e6f-4798-a766-bef5d298cdbc",
  "dev": { "origin": "https://hypermake.localhost", "inspect": true },
  "makeRecipeRoots": ["recipes", "meta/hypermake/src"]
}
		

Recipe sources

Protocol mappings

protocols (object[], project loader) maps protocol names to project directories: {"name": "public", "dir": "rendered/public"}. When the key is absent the defaults are src, cache, build, rendered, public → rendered/public, and the journal directory. Two names are core-owned and cannot be remapped — declared mappings for journal and request-projection are silently dropped and re-forced to their control directories — and the hypermake name maps to the Hypermake home directory unless the project declares it. See Protocols and addresses for how the mapped names behave; hypermake protocols list prints the effective registry.

"protocols": [
  { "name": "src", "dir": "src" },
  { "name": "cache", "dir": "cache" },
  { "name": "rendered", "dir": "rendered" },
  { "name": "public", "dir": "rendered/public" }
]
		

Daemon policy

The dev block

Everything the resident dev service needs lives under dev. The four identity keys use the fallback-chain probe; the block-shaped keys each have their own decoder.

dev.auth shape

All paths are canonical project-relative references; ingress must be one of application-unix-socket, control-unix-socket, private-probe and must be trusted by the referenced deployment policy, or serve refuses to start. exchangeDirectory and loginRedirects must be declared together. The device block enables the device login flow: the signing key is delivered only through the named environment variable, requestTtlSeconds is 1–600, and sessionTtlSeconds is capped by the deployment policy. Values below are placeholders — mint real policy material with hypermake auth owner-ceremony. Serving with authentication documents the policy files, the ceremony, and the refusal contract in full.

"dev": {
  "auth": {
    "policy": "auth/example-instance/deployment.json",
    "ingress": "application-unix-socket",
    "projectPolicy": "auth/example-instance/project-policy.json",
    "exchangeDirectory": "auth/example-instance/exchanges",
    "loginRedirects": ["/"],
    "device": {
      "signerPrivateKeyEnvironment": "EXAMPLE_DEVICE_SIGNER_KEY_FILE",
      "requestTtlSeconds": 120,
      "sessionTtlSeconds": 43200
    }
  }
}
		

dev.companions and hostResources

A companion declares an executable graph target, argv, and health probe; transport is unix-socket only, health exposure is private-control only, and routePrefix may not overlap another companion or the reserved /_hypermake and /lzr-runtime owners. Argv may not embed absolute paths or secret-shaped values; host access goes through declared placeholders: ${socket}, ${origin}, ${root}, and ${host:NAME} for a binding declared in top-level hostResources. Host resource kinds are a closed set: directory (read|read-write/private-path), file (read/private-path), credential-file (read/secret-material), unix-socket (connect/owner-socket).

"hostResources": [
  { "name": "fixture-corpus-root", "kind": "directory", "access": "read-write", "handling": "private-path" },
  { "name": "fixture-corpus-key", "kind": "credential-file", "access": "read", "handling": "secret-material" }
],
"dev": {
  "companions": [
    {
      "schemaVersion": "hypermake.dev-companion.v1",
      "id": "corpus-fixture",
      "executableTarget": "cache://runtime/fixture-server",
      "argv": ["--mode", "corpus", "--listen", "${socket}",
               "--root", "${host:fixture-corpus-root}",
               "--key-file", "${host:fixture-corpus-key}"],
      "transport": "unix-socket",
      "routePrefix": "/_fixture/corpus",
      "bindings": ["fixture-corpus-root", "fixture-corpus-key"],
      "health": { "path": "/health", "exposure": "private-control",
                  "timeoutMs": 250, "retryWindowMs": 3000 }
    }
  ]
}
		

Action packs

actionPacks (object[], project loader) declares digest-locked project code with a declared effect surface. Entry shape: {id, kind, manifest, sourceRoots, modulePath, package?, buildTags?, targetOS?, targetArch?, wasmTarget?, hostABI?, sdkVersion, actions, capabilities?, metadata?}; each action carries {name, version, handler?, effects, capabilities}. Effects come from a fixed vocabulary: path.read, path.write, data.mutate, target.write, process.execute, network.publish, browser.host-call, diagnostic.emit, metric.record, sync.enqueue. Capabilities scope those effects to concrete paths, dataPaths, targets, or hostCalls. This site declares one browser-wasm pack:

"actionPacks": [
  {
    "id": "lzr-testing-admin",
    "kind": "browser-wasm",
    "manifest": "hypermake/browser-action-pack.json",
    "sourceRoots": ["hypermake/browser-actions"],
    "modulePath": "hypermake.local/lzr-testing/browser-actions",
    "wasmTarget": "hypermake.local/lzr-testing/browser-actions",
    "hostABI": "hypermake.browser-action-host.v0",
    "sdkVersion": "hypermake.actionpack.v0",
    "actions": [
      {
        "name": "lzr-testing/admin/update-campaign-title",
        "version": "v1",
        "effects": ["path.read", "path.write", "data.mutate",
                    "browser.host-call", "sync.enqueue"],
        "capabilities": [
          { "kind": "data.mutate", "dataPaths": ["data://campaign.json#/title"] },
          { "kind": "browser.host-call",
            "hostCalls": ["runtime.data.read", "runtime.data.patch"] }
        ]
      }
    ]
  }
]
		

Client graph

Appendix: remaining keys

hypermake doctor
hypermake protocols list
hypermake daemon status
hypermake resolve src://docs/hypermake-json.html