Docs
SupportStatusApp
ProductEngine & CLIAgent Firewall

Upgrading from 0.2 to 0.3

What changes when you move from the 0.2 firewall to 0.3, and the steps to take

Edit on GitHub

This page is for someone who already runs the 0.2 firewall. Every command here is typed by you, in your own terminal. Commands that approve or change state ask for your approval passphrase; never type it into an agent. The full list of changes is in the firewall's changelog, section 0.3.0.

What changes for you

  • Your policy keeps working. Policy files at version 1 or 2 load with the same meaning. The current schema is version 3.
  • Codex needs a reinstall. Codex 0.162.1 silently skips a prompt hook that has a matcher, and 0.2 wrote one. Until you reinstall, the firewall does not see Codex prompts, and doctor fails its Codex prompt hook check.
  • Held approvals are used once. An approval is consumed when it is decided. Two processes can no longer run the same approved action; the second one asks or holds again.
  • A damaged or unsigned vault index asks. With the vault on, a send that carries data asks (rule FW-VAULT-INDEX) instead of passing as if there were no vault.
  • curl and wget with a vault:// reference run only with a short list of options, only to the bound host over https. Plain wget is refused in such a command. Anything else is refused with the option named.
  • uninstall --restore-backup is stricter. It saves the current file as FILE.before-restore.TIMESTAMP, asks (or needs --force) when you changed the settings after install, and refuses a settings file that is a symlink into a protected place (the firewall's directory, ~/.ssh, ~/.gnupg, ~/.aws, another agent's configuration, or outside your home). A symlinked settings file that is not JSON asks first. Dotfiles managers that link ~/.claude/settings.json into your own home still work.
  • Some things block more. Protected paths are matched through symlinked aliases; run refuses DNS answers in private ranges (list a company host in run.privateHosts, user or managed policy only); the administrator's mcpServers entries hold over the user's; a URL in a prompt names only its host; more server names count as mail (m365, o365, exchange, jmap, inbox, mailbox).
  • Gemini CLI's own sandbox (gemini -s) needs a profile, see step 2.
  • The hook loads one bundled file (dist/hook/bundle.js), and the compile cache is now in the firewall's directory, not the temporary directory. Run install again (for each agent): the new hook command sets NODE_COMPILE_CACHE empty, so a compile cache directory named in the agent's environment is not loaded into the hook. Until you do, doctor fails its hook command check. MCP servers wrapped by the gateway need the same: run mcp wrap-config --client <client> again (it adds NODE_COMPILE_CACHE empty to each wrapped stdio entry's env in place); doctor fails its "gateway wrapper" check until you do.
  • New features, off until you use them: run, the vault, the MCP gateway (mcp wrap), the email guard, phone approvals, the Cursor adapter, the dashboard (ui) and the library. Each has its own page in this section.

Steps

Install the new build

Install it the way you installed 0.2 (see the Quickstart), then check:

launchsafe-firewall version          # 0.3.0

Reinstall the hooks, once per agent

Reinstalling is safe to repeat. It keeps your approval passphrase and policy.

launchsafe-firewall install                       # Claude Code
launchsafe-firewall install --agent codex         # required: repairs the prompt hook
launchsafe-firewall install --agent gemini        # if you use Gemini CLI
launchsafe-firewall install --agent cursor        # if you use Cursor

Only for Gemini CLI's own sandbox (gemini -s, macOS):

launchsafe-firewall install --agent gemini --seatbelt BASE   # BASE is the profile your Gemini CLI uses
SEATBELT_PROFILE=launchsafe gemini -s

If you wrapped MCP servers with mcp wrap-config, or paired phones, reinstalling and phone pair or phone remove re-pin them as they do the hooks.

Migrate the policy (optional)

launchsafe-firewall policy validate      # says whether a migration is available
launchsafe-firewall policy migrate       # person-run

policy migrate rewrites your user file as version 3 with the same keys, values and order. The original bytes go to policy.json.v2.bak; an earlier backup is never replaced. A file that does not validate is refused and nothing is written. For a managed or project file, set "version": 3 by hand; nothing else changes.

Do this before you go back to 0.2 on the same machine, if you ever do: an older firewall skips a version 3 file (its other layers still apply) and sends every risky action to a person. Restore policy.json.v2.bak to go back.

Check

launchsafe-firewall doctor               # every line ok, or WARN/FAIL with the fix
launchsafe-firewall status

Look at these lines in particular:

  • The Codex checks: the Codex prompt hook must not fail (if it does, repeat step 2 for Codex).
  • vault (only if you use it): the index signature must verify. If it does not, sends ask until you repair it.
  • The Gemini CLI checks (only if you use gemini -s): the profile, its base and SEATBELT_PROFILE.
  • install record: if install.json is damaged, doctor --repair-state rebuilds it from the agent settings files.

doctor --fix is not needed for the upgrade.

Refresh the package data (optional)

launchsafe-firewall update

Going back

uninstall removes the hooks. uninstall --restore-backup puts each settings file back as it was before the first install; read its prompts, because it now asks about changes you made since.

Limitations

The one list of what the Agent Firewall does not do. Read this before you rely on it.

On this page

What changes for youStepsGoing back