Skip to content

Desktop app ​

Look up the files, menus, environment variables, commands and limits of Humanize Desktop. To use the app, see Humanize Desktop. To install or update it, see Install and update.

Platforms and artefacts ​

Every release on GitHub includes these files:

FileFor
humanize-<version>-macos-universal.dmgmacOS 11 or later, Apple silicon and Intel in one disk image
humanize-<version>-windows-x64-setup.exeWindows 10 or later on x64, with WSL 2
humanize-<version>-macos-universal.app.tar.gzThe signed macOS update the app downloads by itself
humanize-<version>-windows-x64-setup.exe.sigThe signature of the Windows update
latest.jsonWhat the app reads to find an update, for darwin-aarch64, darwin-x86_64 and windows-x86_64

Only releases signed with the updater's key include the last three files. The app never offers an unsigned release as an update.

PropertymacOSWindows
NameHumanize Desktop (menu bar: Humanize)Humanize Desktop
Identifierai.humanfia.humanizeai.humanfia.humanize
Installed asHumanize Desktop.app, dragged to Applications%LOCALAPPDATA%\Humanize Desktop\humanize.exe, for the current user only, no administrator
SigningApple Developer ID and notarized where the release has one, ad hoc otherwiseNot signed
Page address inside the windowtauri://localhost/http://tauri.localhost/
User agent ends withhumanize-desktop/<version>humanize-desktop/<version>
Local daemon routestdio:localstdio:wsl
Installs hmzNeverIn the default WSL distribution, at the app's own version

The app opens .hmzepic files (media type application/vnd.hmz.epic+gzip, macOS type identifier ai.humanfia.humanize.epic). The executable also takes a .hmzepic path as its argument, relative to the current directory. If the app is already running, the second launch hands the file to it: the running app imports the epic and comes forward.

sh
"/Applications/Humanize Desktop.app/Contents/MacOS/humanize" run.hmzepic   # macOS
humanize.exe run.hmzepic                                                    # Windows

What the app downloads ​

WhatVersionWhenWhere it goes
hmzThe app's version (app 0.5.0-rc.1 installs hmz 0.5.0rc1)Windows only, at launch, when WSL has no hmz or one of another versionWSL, as a uv tool
uv0.12.24Windows only, when WSL has no uv on PATH, in ~/.local/bin or in ~/.cargo/bin~/.local/bin/uv in WSL
EasyTier2.6.4The first time an easytier: daemon is openedeasytier/<version>/ in the data directory
The app's own updateNewer than the running version5 seconds after launch, then every 6 hoursReplaces the app

On Windows, the app runs this command in the WSL home directory to install hmz, keeping any <extras> from an existing installation:

sh
uv tool install --force --python '>=3.12' --refresh-package hmz hmz[<extras>]==<version>

The app checks each uv and EasyTier download against a pinned SHA-256 hash. It accepts an app update only if signed with the updater's key, and offers pre-releases only to pre-release builds. It never replaces hmz in WSL while the WSL daemon is running, unless you choose Update now on the launch screen.

Over an ssh route, the app also installs its own version of hmz on the host. See Connect to other machines.

Files the app keeps ​

Data directory ​

The data directory is ~/Library/Application Support/ai.humanfia.humanize/ on macOS and %APPDATA%\ai.humanfia.humanize\ on Windows. The app stores only these entries in it:

EntryHolds
.window-state.jsonThe window's size, position and whether it is maximized
identity/key.pemThe private key of the app's device identity. Written once, readable by you alone
identity/cert.pemThe certificate of the app's device identity. Made again only if it does not match the key
easytier.jsonThe EasyTier entries: each name with its secret and nodes. Readable by you alone
easytier/<version>/The EasyTier programs the app downloaded

If you delete the data directory while the app is closed, the app generates a new device identity on next launch. Previously paired daemons will reject the app until you pair again, and your EasyTier entries and window placement are lost.

Other files ​

FilemacOSWindows
Log, Humanize Desktop.log~/Library/Logs/ai.humanfia.humanize/%LOCALAPPDATA%\ai.humanfia.humanize\logs\
Web view stores (preferences, remote daemons, WebRTC certificate)~/Library/WebKit/ai.humanfia.humanize/ and ~/Library/Caches/ai.humanfia.humanize/%LOCALAPPDATA%\ai.humanfia.humanize\
Single-instance socket, while the app runs/tmp/ai_humanfia_humanize_si.sockNone
Downloads from the page~/Downloads/The Downloads folder
Notification logoNone%ProgramData%\ai.humanfia.humanize\logo.png
While an update installsTemporary directories named tauri_current_app… and tauri_updated_app…, removed afterwardsThe downloaded installer, in the Windows temporary directory

The app empties the log when it exceeds 40,000 bytes. The log records uv install output, opened and closed connections, and update check results. It contains no secrets.

Downloads never overwrite existing files. If a name is taken, the app appends (1), (2) and so on before the extension.

The app writes to hmz directories only by running hmz. See Files on disk.

macOS menu bar ​

MenuItemKeyDoes
HumanizeAbout HumanizeShows the app's name and version
Check for Updates…Looks for an update now and says what it found
Hide Humanize, Hide Others, Show AllThe standard macOS items
Quit HumanizeQuits the app. Epics keep running
EditUndo, Redo, Cut, Copy, Paste, Select AllThe standard macOS items
ViewReload⌘RLoads the page again. Every connection closes and opens again
Actual Size⌘0Sets the zoom to 100%
Zoom In⌘=Multiplies the zoom by 1.1, up to 300%
Zoom Out⌘-Divides the zoom by 1.1, down to 50%
Full screenThe standard macOS item
WindowMinimize, Zoom, Close WindowThe standard macOS items. Closing hides the window
HelpDocumentationOpens https://humanfia.ai/humanize/ in the browser

Standard items use the default macOS shortcuts. Zoom resets when you quit the app. Check for Updates… is disabled in development builds and reads Checking for Updates… during a check. Menus remain in English regardless of the page language.

Windows tray menu ​

Windows has no menu bar. Left-click the tray icon to show the window, or right-click it to open this menu:

ItemDoes
Show Humanize DesktopShows the window
Check for Updates…Looks for an update now and says what it found
DocumentationOpens https://humanfia.ai/humanize/ in the browser
QuitQuits the app. Epics keep running

The top-right window buttons are Minimize, Maximize (Restore Down when maximized) and Close, each 46 by 32 pixels. Close hides the window. Use the standard WebView2 shortcuts to reload and zoom.

Update dialogs ​

DialogButtonsMeaning
Humanize Desktop <version>Restart, LaterAn update is downloaded. Restart installs it now. Later installs it when the app quits
Humanize Desktop is up to dateOKA check by hand found nothing newer
Update failedOKA check by hand failed, with the reason
Update failed: Humanize Desktop cannot replace itself where it is. Move it to Applications, and open it from there.OKmacOS: a check by hand where the app cannot replace itself
Update failed: Humanize Desktop cannot replace itself where it is. Install it for yourself with its setup, and open it from there.OKWindows: the same

During a check by hand, a small Software Update window shows the check, then the download's progress. The app downloads no update where it cannot replace itself. On macOS that is an app run from the disk image, moved aside by Gatekeeper, or in a folder you cannot write; on Windows, one run from outside the folder its setup installed it in.

Environment variables ​

At launch, the app queries your login shell (or the WSL login shell on Windows) for its environment. It waits 5 seconds before falling back to its own environment.

VariableEffect
HUMANIZE_HMZThe hmz to run for Local. The app looks for no other and installs nothing. On Windows the value is a path inside WSL
SHELLThe login shell that is asked. /bin/zsh where it is not set on macOS
PATHWhere hmz and the coding agents are found. The app adds ~/.local/bin, $UV_TOOL_BIN_DIR, /opt/homebrew/bin (macOS only), /usr/local/bin, /usr/bin and /bin where they are missing
UV_TOOL_BIN_DIRAdded to PATH
HTTPS_PROXY, https_proxy, ALL_PROXY, all_proxyOn Windows, the proxy for downloading uv. The first one set in the WSL login shell is used

For variables read by hmz itself, see Environment variables.

Building from source ​

The app is a Tauri 2 project in desktop/, built with pnpm. Run these in that directory:

CommandDoes
pnpm devRuns the app on the page in src/hmz/web/static
pnpm buildBuilds the app and its disk image on macOS, the installer on Windows
pnpm dmg-backgroundDraws the disk image's backgrounds again. macOS only
pnpm nsis-imagesDraws the Windows installer's pictures again

A build from source has version 0.0.0, which makes it a development build. Development builds install nothing on this machine, skip update checks, and run HUMANIZE_HMZ or the first hmz found on PATH or in the fallback directories above. Over stdio:ssh they replace no hmz on the host; where the host has none and the answer to asking is yes, they install the latest release there and use it.

Commands the page may call ​

The page inside the window can call only these app commands. Bytes pass as base64 in data.

CommandArgumentsAnswerDoes
notify{title, body, address}NothingShows a system notification. A click opens address when it is a #/ address of the page of at most 2048 characters
file_read{path, offset, length}{data, eof}Reads a .hmzepic that was opened with the app or dropped on it, at most 1,048,576 bytes a call
pipe_open{route, id}{pipe}Opens a connection to one daemon
pipe_send{pipe, data}NothingSends bytes on a connection that is up
pipe_close{pipe}NothingCloses a connection
pipe_answer{pipe, install}NothingAnswers a connection that is asking: install is true to install hmz on the remote machine, false to leave it. Does nothing for any other connection
easytier_listNoneA list of {name, nodes, secret}Lists the EasyTier entries. secret is only true or false
easytier_set{name, secret, nodes}NothingWrites an entry. Leaving secret out keeps the one written
easytier_remove{name}NothingRemoves an entry

The app sends these events to the page:

EventPayloadMeaning
pipe_state{pipe, state, detail}state is connecting, asking, installing, up or failed. asking waits, with no time limit, for pipe_answer
pipe_data{pipe, data}Bytes from the daemon
pipe_closed{pipe, why}The connection ended. why is closed when the page closed it, otherwise the reason

The page can also drag and zoom the window by its top row, and minimize, maximize and close it on Windows. The app tells the page whether the window is full screen. The page has no other app privileges. Each face runs in an isolated frame and cannot call any commands.

The launch screen has its own commands: status, and on Windows retry, keep and update_now (for the Retry, Continue and Update now buttons). status returns starting or running, and on Windows also installing, waiting, install-failed or missing.

Routes the app opens ​

RouteOpened by
stdio:localThe app, on macOS only
stdio:wslThe app, on Windows only
stdio:ssh://, tcp://, ws://, wss://, easytier:, relay:The app, on both
webrtc:The web view's own WebRTC

On tcp, ws, wss, easytier and relay routes, the app establishes mutual TLS 1.3 using its device identity and verifies the daemon's ID. For the route grammar, see Daemon and wire.

A connection that fails or ends gives its reason as a sentence. The most common are:

ReasonMeaning
<route> cannot be reached from here.The app opens no such route on this platform
<route> needs the id of the daemon it reaches.A route other than stdio: was opened without a daemon ID
hmz is not installed on this machine.macOS: no hmz was found for stdio:local
hmz is not installed on <host>.A stdio:ssh route found no hmz on the host. It is the detail of asking, and the reason the connection fails when the answer is no
hmz could not be installed.A development build installed the latest release on the host, and the install failed without saying why or no hmz answered afterwards
hmz <version> on <host> is too old to be reached: it has no daemon command.The hmz on the host of a stdio:ssh route has no hmz daemon connect, and the app would use it as it is
The latest release of hmz is too old to be reached: it has no daemon command.A development build installed the latest release on the host, found it has no hmz daemon connect, and removed it again
<route> did not open within 30 seconds.The connection or its TLS took too long
<name> is not the daemon it was paired with.The daemon's certificate does not match the pinned ID. Check the address, or pair again
TLS with <name> failed: <why>The TLS handshake failed for another reason
The daemon closed it.The daemon ended the connection without saying why. Otherwise the reason is the last line its process wrote to standard error

Limits ​

LimitValue
Opening a connection, TLS included30 seconds
Finding hmz on an ssh host30 seconds
Installing hmz on an ssh host900 seconds
Waiting for pipe_answer while askingNo limit
WSL starting60 seconds
An update check or download5 minutes
A process still running after quitKilled after 3 seconds
First window size1280 by 820
Smallest window size640 by 480
An EasyTier secretAt least 16 bytes

Content security policy ​

Every page in the window follows this policy:

DirectiveValue
default-src'self'
connect-srcipc: http://ipc.localhost ws: wss:
script-src'self' 'unsafe-inline'
style-src'self' 'unsafe-inline'
img-src'self' data: blob:
font-src'self' data:
frame-src'self'

The main page narrows the policy to script-src 'self', blocking inline scripts; inline scripts run only inside face frames. ipc: and http://ipc.localhost handle app commands. ws: and wss: connect to webrtc: relays.

The window loads only the launch screen and the bundled page. Any http, https or mailto link opens in your default browser; all other addresses are blocked.

Open source on github.com/humanfia · RSS: blog · news