# hankweave.json Hankweave reads an optional `hankweave.json` file from your working directory to pick up runtime settings: which port the server binds, whether a run starts automatically, which model codons use by default, and similar operational choices. This page is the lookup reference for that file. It lists every key the schema accepts, states the type, default and constraints for each, and – most importantly – says whether the setting actually does anything at 0.10.0, because a handful of accepted keys are silently ignored or overridden by another layer. If you are looking for the program file that defines codons and prompts, that is `hank.json`, covered under [Hank configuration](/0.10.0/files/reference/hank-json). This page covers only the runtime configuration file. ## How to read this page Two sources define what `hankweave.json` can contain. The published JSON Schema is the file-shape contract: it lists the allowed keys, their types and their constraints. The runtime's `DEFAULT_CONFIG` block supplies the values used when a key is omitted. Both appear below, and they answer different questions – the schema tells you what you may write, the defaults block tells you what happens when you don't. Each key entry on this page is marked **effective** or **non-operative** at Hankweave 0.10.0, with the relevant constraints, defaults, and precedence rules. Version markers follow the release history: the budget block is \[since 0.6.1], `HANKWEAVE_RUNTIME_SHOW_COSTS` is \[since 0.5.7], and `HANKWEAVE_RUNTIME_EXECUTION_BASE_DIR` is honored \[since 0.8.0]. Output excerpts throughout the page are release-captured material from hankweave 0.10.0. The full key table from the published schema: | field | type | default | required | constraints | description | | -------------------- | --------- | ------- | -------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `port` | `integer` | | no | > 0 | WebSocket server port | | `autostart` | `boolean` | | no | | If true, run immediately on client connect | | `showCosts` | `boolean` | | no | | If true, display cost data in the TUI | | `withoutProxy` | `boolean` | | no | | Bypass internal LLM proxy | | `model` | `string` | | no | minLength 1 | User's preferred default model. Can be a short name like 'sonnet' or 'opus', a Gemini model like 'gemini-2.0-flash', or any model supported by the configured providers. Validation happens at runtime via LLMRegistry. | | `anthropicBaseUrl` | `string` | | no | | Custom Anthropic API base URL (for corporate proxies) | | `outputDirectory` | `string` | | no | | Where to put results (relative to CWD) | | `executionBaseDir` | `string` | | no | | Where to create temp execution environments | | `logParsingInterval` | `integer` | | no | > 0 | Interval for parsing Claude log files (milliseconds) | | `dataHashTimeLimit` | `integer` | | no | > 0 | Time limit for hashing directories (milliseconds) | | `idleTimeout` | `integer` | | no | min 0; max 255 | Idle timeout for WebSocket and proxy servers in seconds (0-255). This is the maximum amount of time a connection is allowed to be idle before the server closes it. A connection is idling if there is no data sent or rece… | | `shimIdleTimeout` | `integer` | | no | > 0; max 1800 | Default shim idle timeout in seconds. Max time between agent events before the shim aborts. Per-codon and hank override settings take precedence. | | `ignoreRigFailures` | `boolean` | | no | | If true, ignore all rig setup failures (useful for resume workflows) | | `sentinel` | `object` | | no | | Sentinel system configuration | | `telemetry` | `object` | | no | | Telemetry configuration | | `budget` | `object` | | no | | | | `$schema` | `string` | | no | | JSON Schema URL for editor support | ```ts export const DEFAULT_CONFIG: Omit< HankweaveConfig, | "cwd" | "readOnlySourceDataPath" | "executionPath" | "agentRootPath" | "rigArchivePath" | "dataPathInExecutionDir" | "dataHash" | "isNewExecution" | "isResuming" | "linkType" | "codons" | "outputDirectory" // Now optional - outputs stay in execution dir by default > = { port: 0, // 0 = OS-assigned dynamic port (avoids collisions on multi-instance runs) version: PACKAGE_VERSION, // Note: outputDirectory is now undefined by default // Outputs stay in the agent workspace ({executionPath}/agentRoot) unless explicitly configured // Informational only — nothing consumes this field. The actual root is resolved // at call time by getManagedExecutionsRoot() in utils.ts (env var HANKWEAVE_RUNTIME_EXECUTION_BASE_DIR). executionBaseDir: path.join(os.homedir(), ".hankweave-executions"), lockFile: ".hankweave/runtime.lock", socketLogFile: ".hankweave/logs/websocket.log", serverLogFile: ".hankweave/logs/server.log", logParsingInterval: 1000, // Check for new log entries every second autostart: true, // Default to current behavior showCosts: false, // Only show cost data in TUI when HANKWEAVE_RUNTIME_SHOW_COSTS is set dataHashTimeLimit: 5000, // 5 seconds for directory hashing toolResultTruncateLength: 2500, // Default truncation length for tool results withoutProxy: true, // Proxy disabled by default (enable with --proxy) handshakeHistoryLimit: 50, // Maximum recent events to include in handshake response idleTimeout: 0, // 0 seconds idle timeout (ie no timeout) for WebSocket and proxy servers (0-255) sentinel: { enablePersistence: true, healthCheckGracePeriodMs: 2000, // 2 seconds waitForAllHealthChecks: false, }, }; ``` Note that the schema table has no values in its defaults column – defaults live in the runtime, not in the schema. The defaults block above also contains internal fields that are not file settings: `version`, `lockFile`, `socketLogFile`, `serverLogFile`, `toolResultTruncateLength`, and `handshakeHistoryLimit`. These appear in `DEFAULT_CONFIG` because the runtime uses one object internally, but you cannot set them through `hankweave.json`. (`TUI` in the table means terminal user interface.) ## Where the file lives and what happens on errors `hankweave.json` is an optional JSON object at `/hankweave.json`. A missing file contributes `{}`, so every setting falls through to the other configuration layers and the defaults. The loader reads this file only from the current working directory; no runtime-config path or CLI flag selects another one. When nested objects appear in more than one layer, they merge key by key rather than replacing the whole nested object. The shipped artifact does not create this file. Running `--init` scaffolds `hank.json` (the program file), prompts, data, and a README – not `hankweave.json`. Automatic `$schema` insertion likewise applies only to `hank.json`. The runtime configuration object is strict at the top level: unknown top-level keys fail parsing. The `budget` and `sentinel` sub-objects are also strict, while unknown keys inside `telemetry` are stripped rather than rejected. A model name is additionally checked against the model registry. What happens on failure is the part that surprises people: these failures are caught by the file-layer loader, and an existing invalid file is silently ignored. There is no warning and no log line; the run proceeds using the other layers and defaults as if the file were not there. > **Pitfall:** A typo, invalid model, or `$schema` property can look like a setting that had no effect, because an invalid `hankweave.json` is silently ignored as a whole. The `$schema` key deserves special attention because the tooling pulls in opposite directions. The published editor schema lists `$schema` as an allowed property, but the runtime parser does not. Putting `$schema` inside this file therefore invalidates the entire file and drops its other settings. Associate the schema in the editor instead, using the published URL: | Schema | URL | | ---------------- | ------------------------------------------------------------------ | | `hankweave.json` | `https://unpkg.com/hankweave@0.10.0/schemas/hankweave.schema.json` | The same schema can be referenced locally from `node_modules/hankweave/schemas/` when Hankweave is installed as a dependency. In VS Code, the association looks like this: ```json { "json.schemas": [ { "fileMatch": ["**/hankweave.json"], "url": "https://unpkg.com/hankweave@0.10.0/schemas/hankweave.schema.json" } ] } ``` One exception to the all-or-nothing failure behavior: telemetry is read directly from the file, separately from the validating load, so the raw `telemetry` object can still be honored when another part of the file fails validation. Telemetry defaults and opt-out precedence belong to [Telemetry](/0.10.0/files/reference/telemetry). And to keep the two files straight: the published schema above is an editor contract for `hankweave.json`; the allowed and required root keys of `hank.json` belong to [Hank configuration](/0.10.0/files/reference/hank-json), not this page. The captured variants below show concrete file values and their observable effects, so you can compare what you wrote against what the runtime did. `{"port":47391}` binds the configured port, `{"autostart":false}` leaves the server waiting for commands, and `{"model":"sonnet"}` shows up in the plan summary. A `$schema` key, as described above, takes the whole file down with it and is silently ignored. *Valid-minimal runtime configuration; output=v0.10.0.* ```json { "port": 47391 } ``` *Autostart-disabled runtime configuration; output=v0.10.0.* ```json { "port": 47392, "autostart": false } ``` *Model-override runtime configuration; output=v0.10.0.* ```json { "model": "sonnet" } ``` *Invalid-schema runtime configuration; output=v0.10.0.* ```json { "$schema": 123, "port": 47393 } ``` *Schema-key runtime configuration; output=v0.10.0.* ```json { "$schema": "https://unpkg.com/hankweave@0.10.0/schemas/hankweave.schema.json", "port": 47391, "autostart": false } ``` The startup captures below correspond to those files. In the valid-minimal capture, the server binds the configured port and reports it in the `Listening on` line: *Valid-minimal startup capture; output=v0.10.0.* ```text ╭────────────────────────────────────────────────────────────────────╮ │ Hankweave v0.10.0 │ │ darwin arm64 • node v23.8.0 │ ╰────────────────────────────────────────────────────────────────────╯ Created new execution directory: ~/.hankweave-executions/ New execution: Source → data Exec → ~/.hankweave-executions/ SDKs → Claude node_modules ✓ ╭──────────────────────────────────────────────────────────────────────────────╮ │ Runtime config: valid-minimal v1.0.0 │ │ 1 codon • 0 loops │ ╰──────────────────────────────────────────────────────────────────────────────╯ └─ [1] write-line (Write one line) model: haiku │ mode: fresh │ prompts: 1 (2 lines) checkpointedGlobs: 1 ══════════════════════════════════════════════════ Hankweave Server Started WebSocket: ws://localhost: ══════════════════════════════════════════════════ Running in headless mode on port Autostart disabled, waiting for WebSocket commands... ➜ Listening on: http://localhost:/ (all interfaces) Shutting down server in 3s... (press Ctrl+C again to force close) Server closed. exit=0 ``` With `autostart: false`, the same startup sequence ends in `Autostart disabled, waiting for WebSocket commands...` instead of beginning the run: *Autostart-disabled startup capture; output=v0.10.0.* ```text ╭────────────────────────────────────────────────────────────────────╮ │ Hankweave v0.10.0 │ │ darwin arm64 • node v23.8.0 │ ╰────────────────────────────────────────────────────────────────────╯ Created new execution directory: ~/.hankweave-executions/ New execution: Source → data Exec → ~/.hankweave-executions/ SDKs → Claude node_modules ✓ ╭──────────────────────────────────────────────────────────────────────────────╮ │ Runtime config: autostart-false v1.0.0 │ │ 1 codon • 0 loops │ ╰──────────────────────────────────────────────────────────────────────────────╯ └─ [1] write-line (Write one line) model: haiku │ mode: fresh │ prompts: 1 (2 lines) checkpointedGlobs: 1 ══════════════════════════════════════════════════ Hankweave Server Started WebSocket: ws://localhost: ══════════════════════════════════════════════════ Running in headless mode on port Autostart disabled, waiting for WebSocket commands... ➜ Listening on: http://localhost:/ (all interfaces) Shutting down server in 3s... (press Ctrl+C again to force close) Server closed. exit=0 ``` The schema-key capture shows the failure mode in action: the file configured a port and `autostart: false`, but because `$schema` invalidated the file, the server binds a dynamic port and autostarts anyway: *Schema-key startup capture; output=v0.10.0.* ```text ╭────────────────────────────────────────────────────────────────────╮ │ Hankweave v0.10.0 │ │ darwin arm64 • node v23.8.0 │ ╰────────────────────────────────────────────────────────────────────╯ Created new execution directory: ~/.hankweave-executions/ New execution: Source → data Exec → ~/.hankweave-executions/ SDKs → Claude node_modules ✓ ╭──────────────────────────────────────────────────────────────────────────────╮ │ Runtime config: valid-minimal v1.0.0 │ │ 1 codon • 0 loops │ ╰──────────────────────────────────────────────────────────────────────────────╯ └─ [1] write-line (Write one line) model: haiku │ mode: fresh │ prompts: 1 (2 lines) checkpointedGlobs: 1 ══════════════════════════════════════════════════ Hankweave Server Started WebSocket: ws://localhost: ══════════════════════════════════════════════════ Running in headless mode on port ➜ Listening on: http://localhost:/ (all interfaces) Shutting down server in 3s... (press Ctrl+C again to force close) Server closed. exit=0 ``` Finally, the validation capture for the invalid-schema variant shows what `hankweave --validate` reports. Note that validation checks the `hank.json` program configuration, not the runtime file – so it passes even though the sibling `hankweave.json` would be ignored at startup: *Invalid-schema validation capture; output=v0.10.0.* ```text ╭────────────────────────────────────────────────────────────────────╮ │ Hankweave v0.10.0 │ │ darwin arm64 • node v23.8.0 │ ╰────────────────────────────────────────────────────────────────────╯ Calculating data signature for validation... > Validating configuration: /fixtures/scenarios/runtime-config/invalid-schema/hank.json Data source: /fixtures/scenarios/runtime-config/invalid-schema/data Execution path: ~/.hankweave-executions/validation- ✓ Configuration is valid! ╭──────────────────────────────────────────────────────────────────────────────╮ │ Runtime config: invalid-schema v1.0.0 │ │ 1 codon • 0 loops │ ╰──────────────────────────────────────────────────────────────────────────────╯ └─ [1] write-line (Write one line) model: haiku │ mode: fresh │ prompts: 1 (2 lines) checkpointedGlobs: 1 ╭─ GOOD TO RUN! ─────────────────────────────────────────────────────╮ │ 1 codons • 1 prompts • 0 system prompts • 0 rigs • 1 checkpoints │ ╰────────────────────────────────────────────────────────────────────╯ Run it: hankweave hank.json ``` See also [Hank configuration](/0.10.0/files/reference/hank-json) for the `hank.json` contract and [Hanks](/0.10.0/files/concepts/hanks) for layer order and model precedence. ## Server behavior keys These keys control the server process itself: which port it binds, when a run starts, and how idle connections are handled. ### `port` Selects the WebSocket (browser/server connection) port. The file value is an `integer > 0`; when omitted, the default `0` asks the operating system for a port, avoiding collisions between instances. The bound port is reported at startup and persisted to `.hankweave/runtime.lock`. **Status:** effective. The configured-port capture in the assertions excerpt below reports `Listening on: http://localhost:47391` and compares the same setting arriving from the environment and CLI layers – all three land on the configured port. See [Execution directory](/0.10.0/files/reference/execution-directory) for the lock file. ### `autostart` Controls whether the server starts immediately when a client connects. It is a `boolean` with default `true`. In `--headless` mode the server autostarts without waiting for a client; `false` leaves it waiting for WebSocket commands. Disable it with `--no-autostart` or `autostart: false` in the file or environment. There is no positive `--autostart` flag. **Status:** effective. The captured `autostart: false` variant reports `Autostart disabled, waiting for WebSocket commands...` and exits with status 0. ### `withoutProxy` Controls the internal LLM proxy. It is a `boolean` with default `true`, so the proxy is disabled by default. Enable the proxy with `--proxy`; when it runs, it prefers `port + 1`. **Status:** effective. See [LLM proxy](/0.10.0/files/reference/llm-proxy) for proxy behavior. ### `idleTimeout` Bounds idle WebSocket and proxy connections. It is an integer from `0` through `255` seconds; default `0` means no idle timeout. **Status:** effective. ### `showCosts` Requests cost display and is a `boolean` with default `false`. **Non-operative in the file at 0.10.0.** The TUI reads `HANKWEAVE_RUNTIME_SHOW_COSTS` directly; no consumer reads the merged file field. The environment variable is the operative cost-display control \[since 0.5.7]. See [Environment variables](/0.10.0/files/reference/environment-variables). The assertions excerpt below summarizes the observed startup behavior across the port and autostart variants, including the environment-variable and CLI spellings of the same settings: *Observed runtime-configuration startup assertions; output=v0.10.0.* ```text hankweave.json {"port":47391}: Listening on: http://localhost:47391 (the configured port) · 1 'Autostart disabled' line(s) · 0 'Auto-starting codon' log line(s) HANKWEAVE_RUNTIME_PORT=47391 (file also present): Listening on: http://localhost:47391 (the configured port) · 1 'Autostart disabled' line(s) · 0 'Auto-starting codon' log line(s) --port 47391 (file also present): Listening on: http://localhost:47391 (the configured port) · 1 'Autostart disabled' line(s) · 0 'Auto-starting codon' log line(s) hankweave.json {"autostart":false}: Listening on: http://localhost: · 1 'Autostart disabled' line(s) · 0 'Auto-starting codon' log line(s) --no-autostart (file also present): Listening on: http://localhost: · 1 'Autostart disabled' line(s) · 0 'Auto-starting codon' log line(s) ``` ## Model and API keys ### `model` Selects one global model for codons. It is a non-empty `string` with no file default. Shortcuts, Gemini spellings, and provider models are checked by the LLM registry. The normal order is CLI > `HANKWEAVE_RUNTIME_*` environment > `hank.json` `overrides.model` > this file's `model` > defaults; `hank.json` `overrides.model` is itself a global override, applied to every codon, including codons inside loops. The resolved value is stamped onto the hank before schema validation, and startup identifies it as applying to all codons. Model spellings belong to [Model resolution](/0.10.0/files/reference/model-resolution). **Status:** effective. The captured `{"model":"sonnet"}` configuration shows the effect in the plan summary: the codon that would otherwise run on its configured model reports `model: sonnet`, and validation exits with status 0. *Model-override validation capture; output=v0.10.0.* ```text ╭────────────────────────────────────────────────────────────────────╮ │ Hankweave v0.10.0 │ │ darwin arm64 • node v23.8.0 │ ╰────────────────────────────────────────────────────────────────────╯ Calculating data signature for validation... > Validating configuration: /fixtures/scenarios/runtime-config/model-override/hank.json Data source: /fixtures/scenarios/runtime-config/model-override/data Execution path: ~/.hankweave-executions/validation- ✓ Configuration is valid! ╭──────────────────────────────────────────────────────────────────────────────╮ │ Runtime config: model-override v1.0.0 │ │ 1 codon • 0 loops │ ╰──────────────────────────────────────────────────────────────────────────────╯ └─ [1] write-line (Write one line) model: sonnet │ mode: fresh │ prompts: 1 (2 lines) checkpointedGlobs: 1 ╭─ GOOD TO RUN! ─────────────────────────────────────────────────────╮ │ 1 codons • 1 prompts • 0 system prompts • 0 rigs • 1 checkpoints │ ╰────────────────────────────────────────────────────────────────────╯ Run it: hankweave hank.json ``` ### `anthropicBaseUrl` Provides a URI for the Anthropic upstream used by `ProxyRunner` when the optional internal proxy is enabled. The proxy is disabled by default. The runner receives the proxy's own URL, not this file value directly. With the proxy disabled, this file key has no effect; the Claude Agent SDK separately passes through an ambient `ANTHROPIC_BASE_URL`, and an enabled proxy URL takes precedence there. This is not a universal Pi or Bedrock gateway setting. **Status:** effective when the internal proxy is enabled. Use the documented `--proxy` switch when enabling that proxy. See [LLM proxy](/0.10.0/files/reference/llm-proxy) and [Authentication and models](/0.10.0/files/operate/authentication-and-models). ## Resource and limit keys These keys control where outputs and executions live and how long various operations may run. Two of them – `executionBaseDir` and `dataHashTimeLimit` – are accepted by the schema but not consumed at 0.10.0, so read their entries carefully before relying on them. ### `outputDirectory` Selects where output copies go. It is a `string` with no default. When unset, outputs stay in the agent workspace at `{executionPath}/agentRoot`; a file value is resolved relative to the original current working directory, and CLI `-o` takes precedence. There is no `hankweave-results` default. **Status:** effective. See [Runbook](/0.10.0/files/operate/runbook). ### `executionBaseDir` Names a managed execution base directory as a `string`, but has no operative file-layer effect at 0.10.0. The managed root is resolved at call time from `HANKWEAVE_RUNTIME_EXECUTION_BASE_DIR`, or from `~/.hankweave-executions` when that variable is absent \[since 0.8.0]. **Non-operative in the file.** `HANKWEAVE_RUNTIME_EXECUTION_BASE_DIR` is the effective way to move the managed root. In contrast, `-e`/`--execution` selects a particular execution directory for a command; it does not make this file key operative. See [Environment variables](/0.10.0/files/reference/environment-variables), [Execution directory](/0.10.0/files/reference/execution-directory), and [CLI: `-e, --execution `](/0.10.0/files/reference/cli#-e---execution-path). > **VersionNote:** Since 0.8.0, the managed execution root moves through `HANKWEAVE_RUNTIME_EXECUTION_BASE_DIR`; `executionBaseDir` remains unconsumed. ### `logParsingInterval` Sets how often codon log parsers check for new entries. It is an integer greater than `0` milliseconds, defaulting to `1000` milliseconds. **Status:** effective. ### `dataHashTimeLimit` Sets a positive integer hashing time limit in milliseconds, default `5000`. **Non-operative in the file at 0.10.0.** Hashing call sites use the `DEFAULT_CONFIG` constant rather than the merged file field. ### `shimIdleTimeout` Sets a harness-shim idle limit: a positive integer of at most `1800` seconds, with no single file default. The fallback is harness-specific–180 seconds for the Claude Agent SDK harness and 120 seconds for the embedded Pi harness. Per-codon and `hank.json` overrides take precedence. **Status:** effective. See [Authentication and models](/0.10.0/files/operate/authentication-and-models) and [Hank configuration](/0.10.0/files/reference/hank-json). ### `ignoreRigFailures` If `true`, makes rig setup failures ignorable. It has no schema or `DEFAULT_CONFIG` default; the effective fallback is `false`. The file key is combined with a per-operation `allowFailure`, and it can also be set through `HANKWEAVE_RUNTIME_IGNORE_RIG_FAILURES` or `--ignore-rig-failures`. **Status:** effective. See [Rigs](/0.10.0/files/concepts/rigs), [Troubleshooting](/0.10.0/files/operate/troubleshooting), and [Environment variables](/0.10.0/files/reference/environment-variables). ### `overwriteOutput` There is no file spelling for output-conflict behavior. This key is not in the file schema; rename-versus-overwrite is controlled by the CLI `--overwrite-output` flag. **Non-operative as a file key.** See [CLI](/0.10.0/files/reference/cli#--overwrite-output). ## How budget ceilings combine ### `budget` Sets persistent ceilings for hank runs. It is a strict object with `maxDollars: number > 0` and `maxTimeSeconds: number > 0`; neither has a default \[since 0.6.1]. Runtime-file and hank-override ceilings combine as `min(runtime, hank)`. An explicit CLI `--max-cost` or `--max-time` then replaces that combined ceiling. Runtime environment variables do not currently support budget settings. This budget merge is separate from per-codon model selection and persisted execution plans. **Status:** effective. See [CLI budgets](/0.10.0/files/reference/cli#timeouts-budgets-and-limits) and [Hanks](/0.10.0/files/concepts/hanks). ## How sentinel settings guide checks ### `sentinel` Configures the runtime sentinel system. It is a strict object with `enablePersistence: boolean` defaulting to `true`, `healthCheckGracePeriodMs: integer > 0` defaulting to `2000` milliseconds, and `waitForAllHealthChecks: boolean` defaulting to `false`. All three are consumed at server start. Per-sentinel `*.sentinel.json` properties and output paths belong to [Sentinel configuration](/0.10.0/files/reference/sentinel-config). **Status:** effective. ## How telemetry settings are read ### `telemetry` Contains `enabled: boolean`, `endpoint: URI`, and `debug: boolean` in a non-strict sub-object. The resolved default is enabled, `debug` defaults to `false`, and the endpoint defaults to `https://hw-telemetry.southbridge.ai`. The object is read directly from the file rather than through the merged validating load – which is why it can survive validation failures elsewhere in the file, as noted above. Opt-out precedence and privacy details belong to [Telemetry](/0.10.0/files/reference/telemetry). **Status:** effective. ### `HANKWEAVE_RUNTIME_TELEMETRY_*` There is no flat runtime-environment spelling for this object. Because the strict runtime schema has no flat `telemetry*` key, a `HANKWEAVE_RUNTIME_TELEMETRY_*` variable causes a startup error instead of configuring telemetry. **Invalid, not a telemetry setting.** Use the file object and the controls documented by [Telemetry](/0.10.0/files/reference/telemetry) and [Environment variables](/0.10.0/files/reference/environment-variables). ## How hankweave.json combines with the configuration layers The entries above repeatedly refer to "other layers" winning or losing against the file. For normal runtime fields, the high-to-low order is CLI arguments, `HANKWEAVE_RUNTIME_*` environment variables, `hank.json` `overrides`, `hankweave.json`, and defaults. Nested objects merge by key. The source comment below records the same order: ```ts * * Configuration layers (in order of precedence, highest to lowest): * 1. CLI arguments (passed as cliArgs parameter) - highest priority * 2. Environment variables (HANKWEAVE_RUNTIME_*) * 3. Hank file overrides (hank.json > overrides) * 4. Runtime config file (hankweave.json) ``` This is the runtime-settings merge only; per-codon model selection and persisted execution plans have their own ownership on [Hanks](/0.10.0/files/concepts/hanks). File keys generally map to `HANKWEAVE_RUNTIME_` variables. Nested sentinel keys use `HANKWEAVE_RUNTIME_SENTINEL_*`; booleans use `true` or `1`, numbers reject `NaN`, and the result is checked against the same schema. Budget settings have no environment keys, and telemetry uses its direct file read instead. The mapping sketch below shows the pattern: ```ts * Load configuration from HANKWEAVE_RUNTIME_* environment variables. * * Parses environment variables with the HANKWEAVE_RUNTIME_ prefix and converts them * to the runtime config structure. Handles type conversions and nested paths. * * Environment variable mapping: * - HANKWEAVE_RUNTIME_PORT -> port (number) * - HANKWEAVE_RUNTIME_MODEL -> model (enum: "sonnet" | "opus") * - HANKWEAVE_RUNTIME_AUTOSTART -> autostart (boolean) * - HANKWEAVE_RUNTIME_SHOW_COSTS -> showCosts (boolean) * - HANKWEAVE_RUNTIME_SENTINEL_ENABLE_PERSISTENCE -> sentinel.enablePersistence (boolean) ``` The full variable table belongs to [Environment variables](/0.10.0/files/reference/environment-variables). ## Settings with no effect through this file Several entries above are marked non-operative or invalid. This table collects them in one place, with the working alternative for each: | Key or spelling | Status at 0.10.0 | Effective alternative | | ------------------------------- | ------------------------------------------------ | ---------------------------------------------------- | | `showCosts` | Non-operative in `hankweave.json` | `HANKWEAVE_RUNTIME_SHOW_COSTS` | | `executionBaseDir` | Accepted but not consumed | `HANKWEAVE_RUNTIME_EXECUTION_BASE_DIR` | | `dataHashTimeLimit` | Merged field is not read by hashing consumers | No file-key alternative is identified here | | `HANKWEAVE_RUNTIME_TELEMETRY_*` | Invalid flat runtime key; causes a startup error | Use the telemetry file object and telemetry controls | The detailed entries above remain the primary contracts; this table is a summary, not a substitute. The schema-key startup capture earlier on the page shows the related `$schema` failure mode: the file uses a dynamic port and autostarts instead of applying its configured port and `autostart: false` values. ## Avoid common configuration mistakes When a setting seems to have no effect, the cause is usually one of these distinctions: * `outputDirectory` has no default; when it is unset, outputs remain in `agentRoot`, not `hankweave-results`. * `executionBaseDir` is accepted but non-operative; use `HANKWEAVE_RUNTIME_EXECUTION_BASE_DIR` for the managed root, and use `-e`/`--execution` to select a particular execution directory. * The file default for `autostart` is `true`; disabling uses `--no-autostart` or the false file/environment value, and there is no positive `--autostart` flag. * `$schema` belongs in editor-side `json.schemas` configuration, not inside `hankweave.json`, because the strict runtime loader omits that property. See also [CLI](/0.10.0/files/reference/cli), [Execution directory](/0.10.0/files/reference/execution-directory), [Environment variables](/0.10.0/files/reference/environment-variables), and [Upgrading](/0.10.0/files/start/upgrading).