Skip to content

Security ​

What to check before you point a flow at work you care about, and what holds an agent back while it works.

Nothing an agent does is put to you for approval

Every flow's agents run with approvals bypassed, whatever flow it is and whether or not you are watching. They edit files, run commands and make commits on their own. What holds an agent back is what its flow declares, below.

At a glance

  • You will make a run you can undo, read what each role of a flow may touch, and know which account every turn is billed to.
  • Use it when you are about to run a flow on a real repository, install a flow, or save an account.
  • You need Humanize installed, and git for the repository the flow works in.

Try it ​

The checklist, before a flow touches anything you care about:

  • The work can be undone. Run in a git repository and tag where you started (git tag start): git diff start then shows everything the flow changed, committed or not, and git reset --hard start takes it back.
  • You have read what each role may touch. It is in the flow's code, not in any menu.
  • You trust every flow you installed. Listing a flow runs its code.
  • You know which account each agent runs as. It is the account row of the agent, and every turn is billed to it.

How it works ​

A flow runs its agents unattended, so the protection has to be decided before the run, not during it. Three things decide it, and none of them is a prompt:

WhatDecided byWhere you check it
what each agent may read, write and reachthe flow, one role at a timethe flow's code, or its page under Flows
whose code runs at allyou, by installing a flow/flow, on its Installed page
whose credentials a turn usesyou, on the agent's account row/flow, and the Accounts page of /settings

Git is what makes the rest safe to try: a tag before the run turns everything the agents did into one diff you can read and one command that takes it back.

Example: read a flow's grants before running it ​

You want to run aot, which writes a flow from a description, in a repository you care about. First, make the run undoable:

sh
cd ~/src/app
git status --short             # nothing uncommitted of yours to lose
git tag start

Then read what its roles may touch. In hmz, open /flow. If aot is not installed yet, press Install more…, open official and install it, then come back to Installed. Put the cursor on aot, tab to Copy here, and press enter:

hmz · /flowdrawn, not recorded
  hmz › /flow › Installed
  …
  ╭────────────────────────────────────────────────────────────────────────╮
   official
   aot                                                               0.1.0
     Writes a flow from a description: drafted, loaded, smoke-run, revie…

   local 1
   @local/aot
     Writes a flow from a description: drafted, loaded, smoke-run, revie…
  ╰────────────────────────────────────────────────────────────────────────╯
   copied to .hmz/flows/aot -- you can edit it, and aot now points to it 2

    Install more…   Update   Uninstall    Copy here    Search…       Save

  enter copy   ←/→ move   tab list   esc back

Now the flow is a directory in your project, and its grants are one search away:

sh
grep -rn "_permission" .hmz/flows/aot
console
.hmz/flows/aot/__init__.py:51:    _permission = Permission(preset="read-only", network=False)

What to look at, by number:

  1. local appears under official: the copy is this project's own flow now, and no update to the installed aot changes what you run.
  2. aot now points to it: $aot and -f aot in this directory run your copy, which is the code you just read.

And in the search result: one role, the critic, declares preset="read-only" and network=False. It reads the draft, never writes, and cannot reach the web. Every role that declares nothing, here all the others, runs at the default in the table below: it writes this directory and nothing else of yours.

Check it worked ​

  • git tag --list start prints start.
  • After the run, git diff start shows everything the flow changed, and nothing outside the repository was written by a role at the default grant.
  • On /flow, each role's account row reads the account you meant, as local or one of yours.

What a flow lets its agents touch ​

A flow declares a permission on each role it drives. You don't choose it at the prompt, so read it in the flow before you run the flow. It has three settings:

SettingWhat it coversA role that says nothing gets
presetthe files: read-only, workspace-write (read anything, write the working directory of the session) or danger-full-accessworkspace-write
networkthe network, the CLI's own web search and fetch among itTrue
granularrules laid over the preset, path by path: allow to write, read_only, deny; the last rule that holds a path decides itnone

What that comes to in practice:

  • Every setting is enforced on the agent and on every command it runs, by Landlock on Linux -- or bubblewrap, where Landlock cannot hold it -- and by Seatbelt on macOS. An agent at the default writes its working directory and nothing else of yours: its CLI's own settings, login and sessions, a temporary directory of its own, the shared /tmp and /var/tmp, the devices, and on Linux /proc. On macOS its login includes the login keychain, which is where Claude Code keeps it.
  • Claude Code, Codex, Grok Build, Qwen Code and pi never write your settings. Each process starts in a home of its own, made for it and removed when it stops: copies of the files the CLI rewrites as it runs (Claude Code's .claude.json, its backups and settings.json; Codex's and Grok Build's config.toml; Qwen Code's settings.json; pi's models.json and settings.json), links to the rest of yours, so its login and sessions are your own, and the flow's skills beside yours (Oh My Pi gets that home for the skills alone). What it writes into a copy, such as that it trusts the workspace, goes with it, and so does what Humanize adds there: Qwen Code's effort, hooks and tool server, a gateway account's model entry for Grok Build or provider for pi. Your system-wide settings and the project's own are read as the CLI always reads them.
  • A rule that writes ~ (allow("~")) lets an agent change whatever your user account may change, anywhere on the machine, the file permissions being what hold it; run as root, the rest of the machine stays as the other rules say.
  • A deny can be undone by a later rule. deny("./.env") followed by allow(".") leaves .env writable, since the last rule that holds a path wins.
  • A read-only role (preset="read-only", with no rule that writes its working directory) also runs in its CLI's read-only mode.
  • network=False cuts the network, except the hosts the agent's model and login are at. The CLI's web tools are switched off too, where it can be told. Those hosts are reached through a proxy Humanize runs on loopback; where your own HTTPS_PROXY, HTTP_PROXY or ALL_PROXY names an http:// proxy, that loopback proxy goes on through yours, except for the hosts your NO_PROXY names.
  • Work in a container or on an ssh host is fenced there too. Every command the agent runs on that machine is held by that machine's own Landlock, bubblewrap or Seatbelt, around its own working directory and home.
  • A grant that cannot be held is refused, not widened. On a Linux kernel without Landlock and with no bubblewrap that starts, on a Mac where Humanize already runs inside another sandbox, and for work on a machine like either, a role runs only at danger-full-access with network=True and no rule that takes anything back. A role with a rule this machine's sandbox cannot carve out is refused too.
  • Unless you hand it to Codex. A machine whose sandbox.native names codex lets Codex's own sandbox hold its grant instead: what the commands it runs may write and reach, and not Codex itself, its MCP servers or its hooks, nor what anything reads. The agent says so once. See Permissions.
  • Some ways out remain. Neither Landlock nor Seatbelt governs a Unix socket reached by its path, so an agent can still talk to a socket another program listens on, a docker daemon's among them; on macOS a system service reached over Mach is the same. On a Linux kernel older than 6.12 (Landlock ABI 6), an agent can also signal processes outside its fence and reach their abstract Unix sockets. With network=False on macOS, a program the agent runs may serve on any address, not only loopback. And whatever an agent can write, a later run can read.

Permissions lists what the official flows declare, and how each CLI holds to it.

Listing a flow runs its Python ​

A flow is a directory of Python, and Humanize runs it to find out what it is. Opening /flow, or naming a flow after $ at the prompt, runs every flow Humanize lists: the ones built in, the ones you installed, this project's and yours.

Installing a flow from a flowverse therefore trusts the repository it comes from with this machine, the way installing a package does: install only the flows you would install as one. Adding a flowverse runs nothing: it is an index of releases, and holds no code. official is always there: it is Humanize's own, at humanfia/flowverse, and its maintainers review every release it lists, which lowers the risk without removing it.

An installed flow is the exact commit its release names, and stays that commit until you update it: hmz fetches the flowverses each time it opens, and only says when a newer release is listed. To keep a flow as you read it whatever you install later, put the cursor on it in /flow and press Copy here, as in the example: it is copied into this project's own flows, and the flow's name here runs the copy.

Where your credentials are ​

An agent runs asHumanize keeps
as local, the defaultnothing. The CLI reads its own login, where it always keeps it.
a login made on the Accounts page of /settingsthe files that CLI wrote when it signed in, under ~/.hmz/providers/<cli>/<name>/
a key or a gateway made on the Accounts page of /settingswhat you typed, the key and a gateway's URL, in provider.json in that same directory
  • Those directories and files are readable by you alone.
  • The Accounts page of /settings names the variables an account sets and never shows their values. A secret you type is drawn as bullets.
  • A turn run as an account from /settings has the keys other accounts would use unset, so a key left in your shell profile cannot take its place.
  • Removing ~/.hmz removes every account. The CLIs' own logins stay where they are.

How an account's credentials reach a turn is in the Providers reference.

Other things worth knowing ​

  • Reporting. Humanize reports what goes wrong to its developers only if you said yes when it first asked. A report carries more than a crash; Reporting lists what is sent and what never is.
  • A remote target served over TCP is a shell on that machine for anyone who can reach the port and holds its token. The session is encrypted and the token is never sent, but the token is the whole of its protection: give it a real one, or prefer ssh:// and docker://. See Remote execution.
  • /afk is about questions, not actions. It decides whether a flow may ask you something. It never makes an agent ask before it acts.
  • A dsh agent works with full access whatever its flow declares.
  • A project's hooks run only on the project's own machine. Project settings such as Claude Code's hooks or a .mcp.json stdio server start programs where the CLI runs. If a flow's agent runs on a different machine from its environment's work (harness local with the work elsewhere, or a harness runtime other than the work's machine), Humanize refuses to open the session while the project has any such setting. Run the agent on that machine (harness env), or remove the setting. See Remote execution.

Troubleshooting ​

A role is refused before the run starts ​

Its grant cannot be held here: on a kernel without Landlock and with no bubblewrap that starts, on a Mac where Humanize runs inside another sandbox, or on a machine like either, only a role at danger-full-access with network=True and no rule that takes anything back runs. And a cursor-agent role with network=False is refused on every machine, because Cursor's web tools cannot be switched off. Run the flow on Linux with Landlock or bubblewrap, or on macOS outside any other sandbox, or choose another CLI for the role. See Permissions.

The flow changed things I did not expect ​

Read them all with git diff start, and take them back with git reset --hard start. Commits the agents made are undone too, since the tag is older. Files outside the repository are not in git: a role at the default grant cannot write there, but one at danger-full-access, or with a rule such as allow("~"), can.

A flow I read last week behaves differently ​

It was updated: an update installs the newer release over the one you read. Choose the release you read on the flow's page in /flow (Switch to), then Copy here to keep it as it is.

A turn was billed to the wrong account ​

The agent's account row decides it. Open /flow, enter on the role, and check account. An account that does not exist fails every turn of that agent, naming it; it never falls back to as local quietly.

Reporting a vulnerability ​

Report it privately, never in a public issue: SECURITY.md says how, what counts as a vulnerability, and when you will hear back.

Next steps ​

  • Permissions: what each official flow grants, and how each CLI holds it.
  • Accounts: API keys, gateways and second logins, kept apart.
  • Flowverses: what installing a flow means, and publishing your own.
  • Containers: put the work somewhere a mistake cannot reach you.

Released under the Apache-2.0 licence.