Skip to content

Settings ​

Every setting Humanize persists: its key, scope, type, default, the file it is stored in, who writes and reads it, and when a change takes effect. The screen that edits them is /settings; the Python object is Hmz().settings (hmz.runtime.settings.Settings, internal).

Stores ​

StoreFileScopeEdited on /settings pageReference
settingsH/settings.yamlthis machine, and per workspaceGeneral, Workspace (and /flow)this page
accountsH/providers/<cli>/<name>/provider.json; CLIs added by hand under clis in H/settings.yamlthis machineAccountsProviders, Files
runtimesruntimes in H/settings.yamlthis machineRuntimesMachines
nousnous in H/settings.yamlthis machineNousthis page
backupsbackup in H/settings.yaml; clones cached under hmz.machine()/backup/<name>/this machinenone yet: settings.yamlthis page
flowversesH/flowverses/<name>/index/ (index clones), H/flowverses/<name>/installed/[<user>/]<flow>/ (installed flows)this machinenone: /flow › FlowversesFlows

H is $HUMANIZE_HOME, else ~/.hmz. A workspace is identified by its absolute, symlink-resolved path.

settings.yaml ​

yaml
workspaces:
  /home/you/code:                  # one entry per workspace
    flow: rlar                     # the flow last set up here
    chat:
      agent: claude/claude-opus-5:high  # the agent a new chat here starts with
    flows:
      rlar:                        # one entry per flow set up here, by listed name
        agents:
          actor: claude/claude-opus-5:high
          reviewer: codex@work/gpt-5.6-sol:high
        envs:
          box: ssh@gpu-box/home/you/code
        params:
          rounds: 5
        budget:
          duration: PT6H
          cost: 20.0
          output_tokens: null
          graceful: true
        profile_flow: true         # profile the flow's Python in a run started from the TUI
        profile_environment: true  # and the programs its agents start
        backup: [lab]              # the targets an epic of it goes to; [] for none
        harness: local
enable_sentry: false               # this machine
details: true                      # this machine
btw: claude/claude-opus-5:high     # this machine
ai_chan: claude/claude-opus-5:high # this machine
every_epic: true                   # this machine
chat:                              # this machine
  prefer: native                   # native or flow: what `$<name>` is in a chat where both
sandbox:                           # this machine; written by hand
  backend: auto                    # auto, landlock or bwrap: what holds a grant on Linux
  native: [codex]                  # CLIs whose own sandbox holds their grant instead
daemons:                           # this machine; /settings daemons
- name: gpu
  id: ""                           # pinned the first time it answers over a trusted route
  routes: ["stdio:ssh://me@gpu.example:22?identity=~%2F.ssh%2Fid_ed25519"]
- name: lab                        # an ssh config host, resolved each time
  id: ""
  routes: ["stdio:ssh://lab"]
- name: home                       # paired from its code: `hmz daemon pair` there
  id: j2quawebkb3tzy5kzz4gv3xx6qcjzyia7jsjzfh3xxnzmdy5vfba
  routes: ["tcp://home.example:41817", "easytier:home"]
notifications:                     # this machine; /settings notifications
  kinds: {done: true, failed: true, stopped: true, asked: true, listening: true}
  system: true
spelling: 2                        # how envs are spelled; written with every change
nous:                              # this machine; the Nous page
  claude@work/claude-opus-5:
    tries: 3
    policy: exponential
    timeout: 600.0
    then: [codex/gpt-5.6-sol, dsh/deepseek-v4-flash]
  smart:
    tries: 0
    policy: exponential-jitter
    timeout: 0.0
    graph:
      start: pool
      nodes:
        pool: {balance: least-busy, among: {claude@work/claude-opus-5: 1, claude@team/claude-opus-5: 2}, next: cheap}
        cheap: {use: dsh/deepseek-v4-flash}
clis:                              # this machine; added on the Accounts page
  my-agent: [my-agent, --acp]
runtimes:                          # this machine; the Runtimes page
  ssh:
    gpu-box: {host: 10.0.0.2, user: you, port: 0, ...}
backup:                            # this machine
  targets:
  - name: lab
    url: git@github.com:you/epics.git
    branch: main
    policies: [session, interval, end]
    every: 30
  defaults: [lab]

Machine settings ​

KeyTypeDefault (absent)Written byRead byTakes effect
enable_sentryboolabsent: nobody has been asked; the TUI asks at its first start; everything else reports nothingthe first-start question; /settings › General › Error reportsevery process that could report (read once per process)immediately in the process that changed it; at start elsewhere. HUMANIZE_SENTRY overrides it for one process without writing it. Reading never writes it.
detailsbool (only true is on)false/settings › General › Detailsthe TUIimmediately: turns show every tool call and all thinking instead of responses only
ai_chanstr: a nous's name, or cli[@account]/model:effort"": no default, /ai asks for one/settings › General › Ai-chan; web Settings › General › Ai-chanthe TUI and the web page, as their forms' default; the daemon, as aichan.create is given no nousthe next Ai-chan conversation made; one made keeps its nous
every_epicbool (only true is on)false: this directory'sctrl+t on /epicsthe TUIthe next time /epics is opened
chat.preferstr: native or flow (any other value reads as native)native/settings › General › Chat prefers for $; settings.set preferevery chat, through its hostthe next $ line of every chat that has no preference of its own (/prefer, the web's toggle, chat.set), which is kept in that chat's epic
daemonslist of {name, id, routes}: id the daemon id pinned, 52 base32 characters, or "" until it first answers over a trusted route, which pins it; routes the routes it is reached by (Section 3.3 of protocol/wire.md), in the order they are raced, the first a trusted one (stdio:ssh://…, stdio:local, stdio:wsl) where id is "". An entry an earlier release wrote, {via, host, user, port, identity_file, proxy_jump, options, alias} or {via: easytier, secret, peers}, is read as the stdio:ssh or easytier:<name> route it reached, and written so at the next write, an EasyTier one's secret and nodes moving to easytier[]: Local aloneRemotes.pair from a pairing code, the terminal interface's Daemons page and its Import…the terminal interface, hmz exec, the SDK; never the web page, which keeps its ownat once: a daemon added is reached the first time it is asked for, one removed is let go of
notifications{kinds: {done, failed, stopped, asked, listening}: bool, system: bool}every kind told, and shown by the system too; only false turns one off/settings notificationshmz; never the web page, which keeps its ownimmediately: the next notice of a kind is told or not
sandbox{backend: str, native: [str]}backend: auto (any value but landlock and bwrap reads as it); native: [] (an entry that is not a string is ignored)nobody: written by handevery process that fences an agent: backend where the fence is put up, on that machine; native by the Codex driverat the next turn fenced. backend picks Landlock or bubblewrap on Linux, auto being Landlock where it can hold the grant and bubblewrap otherwise; native names CLIs whose own sandbox holds their grant around the commands they run alone, of which only codex is honoured. See Permissions
envs{paired_terminals: bool}paired_terminals: false (only true is on)nobody: written by handthe daemon, at each call that opens or types into a terminalat the next such call. true lets a paired device, or a session over EasyTier, open a shell in an epic's environments; a session on this machine or over SSH always may. See Into its environments
spellingintabsent: written before -e wrote @ only before a providerevery write of the file, as 2every process, as it reads the fileabsent, envs are read as their old spelling meant and rewritten once; 2, as written

What error reports contain and exclude is listed on /settings › General › What is sent.

Workspace settings ​

Under workspaces.<path>.

KeyTypeDefaultWritten byRead byTakes effect
flowstr, a listed flow nameabsent (Settings.flow is ""): no flow set up here/flow when savedthe TUI at start, as the flow /flow and $ lines start from; the TUI always opens on a new chatnext launch
chat.agentstr, an agent as -a spells one after <role>=absent (Settings.chat_agent is None; one an earlier Humanize wrote as the assistant of flows.chat.agents is read in its place); the TUI then fills it by defaultstarting a chat from the TUI or the web, /model or /effort in one, /settings › Workspace › Chat agent, settings.set chat; never flow or a flow's entrythe TUI, the web's New epic › Chat, and hmz chat given no -athe next chat started here
flows.<flow>mappingabsent/flow when savedthe TUIsee below

/settings › Workspace also shows Default flow (read-only), Chat agent, and Forget: on save it deletes this workspace's entry; the TUI already open keeps what it loaded, and the next launch starts without it.

Per flow ​

Under workspaces.<path>.flows.<flow>, keyed by the flow's listed name (rlar, alice/kernel, @local/twice, @theirs/review, humanize1:gen-plan), so a local flow never inherits the setup of the built-in or installed flow it shadows.

KeyTypeMeaningRead back
agents{role: str}each agent role's cli[@account]/model:effort (the -a spec after <role>=)an entry that does not read as cli[@account]/model:effort (split at the first / and the last :) makes the whole agents mapping read as absent
envs{role: str}each environment role's -e spec after <role>=any non-string value makes the mapping read as absent; in a file with no spelling, a spec in the spelling -e refuses with a hint (local@/x, docker@local/x, swarm@local/x, apple-container@local/x, slurm@local/x, an unsaved ssh host out of brackets) is rewritten in the one the hint gives, in every workspace, when the file is first read
paramsmappingthe params, as JSONvalidated through the flow's current params model; a failure reads as not set up
budget{duration, cost, output_tokens, graceful}the budget as Budget.model_dump_json writes it (duration ISO 8601, cost "Infinity" for unlimited, graceful a bool or {duration, cost, output_tokens} of bools)validated as a Budget; a failure reads as absent
profile_flowbool, written only as truewhether a run of the flow started from the TUI or the web profiles the flow's own Python, set on the /flow menu's profile flow rowanything but true reads as off
profile_environmentbool, written only as truewhether a run of the flow started from the TUI or the web profiles the programs its agents start, set on the /flow menu's profile environment rowanything but true reads as off
backup[str]the backup targets an epic of the flow goes to, by name, as Options → Backup in hmz web saved them; [] is noneanything but a list reads as absent, which is the defaults; a name settings has no target of is dropped by whoever starts the epic

Writing. Saving /flow replaces the flow's whole entry and sets flow. agents is always written; envs, params, budget, profile_flow, profile_environment and backup are written as given, carried over from the file where the caller passes none, and an empty value (or a profiling switch off) erases the key -- but an empty backup, which is kept as none. A harness key an older Humanize wrote is dropped at the next save.

Reading. When the TUI starts a flow without opening /flow (a $flow line, or /flow <flow> <task>), it uses the remembered setup only if it is complete: the remembered agent roles equal the flow's declared agent roles; every required environment role is remembered; the params still validate; a budget is remembered. Otherwise /flow opens to ask. profile_flow and profile_environment go with the rest. hmz exec and Hmz().run never read flows; they use only their own arguments (--profile-flow, --profile-environment, profile_flow=True, profile_environment=True).

nous ​

Nous, written by /settings › Nous and Hmz().nous. A mapping from each nous's name -- a concrete nous CLI[@ACCOUNT]/MODEL[:EFFORT], or a virtual nous's name, [A-Za-z][A-Za-z0-9_.-]* and no CLI's -- to:

FieldType
triesintretries before then
policystrnone, constant, linear, exponential, exponential-jitter, fibonacci
timeoutfloatseconds, 0 for no limit
graphgrapha virtual nous's graph; never on a concrete one
thengraphwhere a turn goes once the tries are spent

A graph is one nous, a list of nous tried in turn, or {start, nodes}, nodes mapping each node's id to {use: <nous>} or {balance: <strategy>, among: {<nous>: <weight>}, spread: <n>}, with on: {<fault class or *>: <node id>} or next: <node id> (the same as on: {'*': …}). A chain is written back as a list. Invalid entries are dropped on read; a write that would name a virtual nous nobody wrote, or let nous name one another round, is refused. A fallbacks list an older Humanize wrote is read as each spec's then: <to>, and dropped at the next write.

clis ​

CLIs added on the Accounts page, driven over ACP. A mapping from name to either an argv list or {command: [...], hosts: [...], state: [...]} (hosts, state are set by hand: the hosts it may reach with network=False, and extra paths it may write). A host is name, name:port, *.suffix or an IP address; one written as a URL is read as its host and port (https://api.example.com/v1 is api.example.com), and one that names no host is dropped with a warning, so a list of nothing else counts as no hosts. Removing the key forgets every added CLI.

runtimes ​

Runtimes, written by /settings › Runtimes and Hmz().runtimes: runtimes.<backend>.<name>, <backend> ssh, docker, swarm, apple-container or slurm. The backend and the name are where the entry is, whatever it says; an entry that does not validate is skipped. A runtime an earlier Humanize wrote with an ordered affinity list is read as though its harness were the list's first entry (self read as env), and as having none where the list is empty; the next write of it drops affinity.

ssh:

FieldType
host, user, identity_file, proxy_jump, alias, config, workdirstr
portint
options{str: str}
fallback[str], each <backend>:<name>
harnessstr: env (default), local or <backend>:<name>, not the runtime itself
made"typed" or "imported"

docker:

FieldType
tls_dir, image, runtime, name_prefix, workdirstr
endpointlocal, unix://…, tcp://…, ssh://…, ssh:<ssh runtime>, context:<name>
containerstr: a running container every environment works in (A running container)
exec_userstr: UID[:GID]
exec_env, exec_wrapper[str]: NAME=VALUE each; the wrapper's words
run_args, gpus, fallback[str]
harnessstr, as for ssh
cpusfloat
memory, gpu_memory, max_containersint
made"typed"

swarm:

FieldType
tls_dir, image, name_prefix, gpu_resource, workdirstr
endpointa swarm manager, as a docker runtime's endpoint
run_args, constraints, fallback[str]
harnessstr, as for ssh
cpusfloat
memory, max_tasksint
nodes{str: str}: a node's host name to a saved ssh runtime's name or [user@]host[:port]
made"typed"

apple-container: image, workdir, harness (str), run_args, fallback ([str]), cpus (float), memory, max_containers (int), made ("typed").

slurm:

FieldType
partition, account, qos, constraint, workdirstr
timestr: minutes, MM:SS, HH:MM:SS, D-HH[:MM[:SS]], UNLIMITED or INFINITE
pythonstr: absolute, or under ~/; accepted and not used
via"srun" or "tcp"
run_args, fallback[str]
harnessstr, as for ssh
cpusfloat
memory, max_jobs, max_waitint
made"typed"
yaml
runtimes:
  slurm:
    hpc:
      partition: batch
      account: myteam
      time: '04:00:00'
      via: tcp
      max_jobs: 8
      max_wait: 600
      workdir: /lustre/me/project

backup ​

The git repositories epics are backed up to, written by Hmz().settings.back_up_to(targets, defaults) -- which the Backup page of /settings saves through -- and read by every process that runs an epic, as the epic starts.

KeyTypeDefaultMeaning
targets[].namestr: a letter or digit, then letters, digits, - and _, 32 at mostrequiredWhat --backup, --to and defaults name it. Unique.
targets[].urlstrrequiredWhere git pushes to, with this machine's own ssh key or credential helper.
targets[].branchstrmainThe branch epics are committed to; made where the repository has none.
targets[].policieslist of session, interval, end[]: by hand onlyWhen an epic is backed up there unasked.
targets[].everyint ≥ 130Minutes between interval backups of a running epic.
defaultslist of target names[]The targets an epic goes to when it is started without saying.

A target that does not validate is skipped as the file is read, and a default naming no target is dropped; back_up_to refuses both with ValueError and writes nothing. Each backup's outcome is a backed line in the epic's epic.jsonl (to, ok, error, why).

File behaviour ​

BehaviourRule
Missing, unreadable, invalid YAML, not a mappingread as empty; never prevents a start
Unknown keyskept at the top level and in a workspace entry; a flow's entry is replaced whole when /flow is saved
Writeeach change is written at once: take flock(LOCK_EX) on .settings.yaml.lock beside the file; re-read the file; make this one change to what it holds now (one machine key, one workspace's flow and one flow's entry, one workspace removed, or the whole of nous, clis, backup or one runtime); write .settings.yaml.<random>.new (mode 0600 for a new file, the existing file's otherwise), fsync, rename over; release the lock. The writer then holds what it wrote. A file that exists but does not read as a mapping is never written over: it is left for whoever is editing it to correct.
Concurrent writersserialized by the lock. A write changes only what it is about: every machine key, workspace, workspace key and flow entry another writer wrote survives it, whenever this writer read the file. envs, params, budget, profile_flow, profile_environment and backup not handed to a /flow save are carried over from the file as it is at the write. Two writes to the same key or the same flow's entry: the later wins. A writer that cannot open the lock file, gets an error from flock, or has waited 30 s for it writes without it.
Write failure, or a file that does not read as a mappinga Settings holds the change in memory and writes nothing; a nous, added CLI or runtime is refused with OSError

/settings rows ​

PageRowKeyKind
GeneralDetailsdetailsswitch
GeneralAi-chanai_chanpick
GeneralChat prefers for $chat.preferpick: native, flow
GeneralError reportsenable_sentryswitch
GeneralWhat is sent—shows the lists
WorkspaceDefault flowworkspaces.<path>.flowread-only
WorkspaceChat agentworkspaces.<path>.chat.agentagent sheet
WorkspaceForgetdeletes workspaces.<path>switch

Changes are held until saved (the save button, or the question asked on leaving). The pages Accounts, Runtimes and Fallback edit the other stores; the flowverses are edited on /flow. /settings <page> opens a page by name: general, accounts, nous, runtimes, workspace (also settings and everywhere for general, directory for workspace, environments for runtimes; flowverses opens /flow on its Flowverses page). The Workspace page names its directory across its top rather than as a row.

Released under the Apache-2.0 licence.