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. 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:

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 <cwd>/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.

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:

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.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. 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, 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.

{
  "port": 47391
}

Autostart-disabled runtime configuration; output=v0.10.0.

{
  "port": 47392,
  "autostart": false
}

Model-override runtime configuration; output=v0.10.0.

{
  "model": "sonnet"
}

Invalid-schema runtime configuration; output=v0.10.0.

{
  "$schema": 123,
  "port": 47393
}

Schema-key runtime configuration; output=v0.10.0.

{
  "$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.

╭────────────────────────────────────────────────────────────────────╮
│  Hankweave v0.10.0                                                 │
│  darwin arm64 • node v23.8.0                                       │
╰────────────────────────────────────────────────────────────────────╯

Created new execution directory: ~/.hankweave-executions/<exec-id>
New execution: <exec-id>
  Source → data
  Exec   → ~/.hankweave-executions/<exec-id>
  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:<port>
══════════════════════════════════════════════════

Running in headless mode on port <port>
Autostart disabled, waiting for WebSocket commands...
➜ Listening on: http://localhost:<port>/ (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.

╭────────────────────────────────────────────────────────────────────╮
│  Hankweave v0.10.0                                                 │
│  darwin arm64 • node v23.8.0                                       │
╰────────────────────────────────────────────────────────────────────╯

Created new execution directory: ~/.hankweave-executions/<exec-id>
New execution: <exec-id>
  Source → data
  Exec   → ~/.hankweave-executions/<exec-id>
  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:<port>
══════════════════════════════════════════════════

Running in headless mode on port <port>
Autostart disabled, waiting for WebSocket commands...
➜ Listening on: http://localhost:<port>/ (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.

╭────────────────────────────────────────────────────────────────────╮
│  Hankweave v0.10.0                                                 │
│  darwin arm64 • node v23.8.0                                       │
╰────────────────────────────────────────────────────────────────────╯

Created new execution directory: ~/.hankweave-executions/<exec-id>
New execution: <exec-id>
  Source → data
  Exec   → ~/.hankweave-executions/<exec-id>
  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:<port>
══════════════════════════════════════════════════

Running in headless mode on port <port>
➜ Listening on: http://localhost:<port>/ (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.

╭────────────────────────────────────────────────────────────────────╮
│  Hankweave v0.10.0                                                 │
│  darwin arm64 • node v23.8.0                                       │
╰────────────────────────────────────────────────────────────────────╯

Calculating data signature for validation...

> Validating configuration: <workspace>/fixtures/scenarios/runtime-config/invalid-schema/hank.json

  Data source:    <workspace>/fixtures/scenarios/runtime-config/invalid-schema/data
  Execution path: ~/.hankweave-executions/validation-<id>

✓ 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 <data_path>

See also Hank configuration for the hank.json contract and 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 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 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.

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.

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:<dynamic port — NOT 47391> · 1 'Autostart disabled' line(s) · 0 'Auto-starting codon' log line(s)
--no-autostart (file also present): Listening on: http://localhost:<dynamic port — NOT 47391> · 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. 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.

╭────────────────────────────────────────────────────────────────────╮
│  Hankweave v0.10.0                                                 │
│  darwin arm64 • node v23.8.0                                       │
╰────────────────────────────────────────────────────────────────────╯

Calculating data signature for validation...

> Validating configuration: <workspace>/fixtures/scenarios/runtime-config/model-override/hank.json

  Data source:    <workspace>/fixtures/scenarios/runtime-config/model-override/data
  Execution path: ~/.hankweave-executions/validation-<id>

✓ 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 <data_path>

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 and 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.

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, Execution directory, and CLI: -e, --execution <path>.

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 and Hank configuration.

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, Troubleshooting, and 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.

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 and 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. 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. 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 and 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:

 *
 * 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.

File keys generally map to HANKWEAVE_RUNTIME_<SNAKE_CASE> 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:

 * 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.

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:

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, Execution directory, Environment variables, and Upgrading.