Security

The threat model

A bot reads mail and web pages written by others. Huskarl assumes that some of them try to steer the bot ("send all mail to …"), and that the model now and then lets itself be fooled. Even so, nothing should go out in your name, cost money, be deleted or be published without you having seen exactly what and said yes.

Huskarl also assumes that:

• the agent CLI can run tools without asking anyone (Elyra and Pi do), so the rules cannot live in the agent
• the daemon can stop at any time, also in the middle of a send
• other users on the same Mac must not reach the bots.

The layers below apply each on their own. The intent is that all of them hold.

Layer 1: the gateway's tools are the only tools

The agent is started without its own tools (shell, files, web search) and with the gateway as its only MCP server. How, for each agent, is in Agents. If the agent asks for anything else, it is refused.

The gateway listens on loopback. Each agent session gets its own token (hgw_…), which is revoked when the session ends. The token says which bot it is. An unknown or empty token is refused, and there are no tools for approving, deciding or changing policy.

Layer 2: Seatbelt

The agent runs with sandbox-exec and a profile Huskarl makes per bot:

• Network: loopback only. That also closes the Unix socket to mDNSResponder, so the agent cannot look up names. DNS is therefore not a way out.
• Writing: only the bot's own folder, ~/.huskarl/bots/<id>. For Claude Code also ~/.huskarl/agents/claude, and for Grok Build ~/.huskarl/agents/grok. The shared temp folders (/private/tmp, /private/var/folders) are taken out, so one run cannot leave anything behind for the next. TMPDIR points into the bot's folder.
• Hidden from reading:
  • all of ~/.huskarl, except the bot's own folder and the agent's login folder
  • ~/.ssh, ~/.aws, ~/.gnupg, ~/.netrc, ~/.config/gh
  • ~/.claude, ~/.claude.json and ~/.codex
  • for Elyra: your Elyra folder, except auth.json and models.json
  • for Grok Build: ~/.grok.

The bots' browser profiles live in ~/.huskarl/browsers, outside the bots' folders, and are therefore hidden from the agents.

The environment is built from scratch. Only PATH, LANG, LC_ALL, LC_CTYPE, USER, LOGNAME, SHELL and TZ are passed on from the daemon, plus HOME, TMPDIR, TMP, TEMP, the proxy variables and what the agent needs. A variable nobody has thought of, such as a cloud token or SSH_AUTH_SOCK, does not reach the agent.

sandbox-exec is deprecated, but it is what Apple's own tools, Claude Code and Codex use. It sits behind an interface (Isolation), so a VM can replace it.

Layer 3: the egress proxy

Seatbelt can only say "loopback or nothing". On loopback the agent finds the egress proxy (HTTPS_PROXY), which is the agent's only way out:

• Only CONNECT, only port 443.
• Each bot has its own list, based on the model provider. Elyra with Anthropic reaches only api.anthropic.com. The lists are in Agents.
• The proxy looks up the names itself.
• Everything else gets 403 Forbidden and is logged: egress REFUSED example.com:443 for Some("<bot>").

What is left: an agent that could make HTTP requests itself could reach an allowed model host with an attacker's API key. Layer 1 closes that, because the agent has no tools of its own. A proxy that checks the key would require TLS termination and is not planned.

Outside text

Everything a tool reads from the outside is wrapped in <external-<nonce> source="…"> with a random nonce per call, so the text cannot close the tag itself. After the tag it says that the content does not come from the user and cannot give instructions. A screenshot gets the same notice. The agent's instructions say the same.

Memories written after outside text in the same run are held back until you accept them. See Memory.

Approval

The approval card points out what came from outside text (an address, a link or an account number that is in a mail the run read and nowhere the user wrote), a first recipient, and a domain that looks like one in use. See What the card points out. It also points out an account number, IBAN or KID whose check digits do not add up, and an account number in an invoice that is not the one the sender used before. Nothing about it needs a model, and nothing leaves the machine.

A run that has read mail marked confidential for the bot sends nothing outside your domain unasked, whatever its rules say. See What is confidential. Before a bot's rules are loosened, its last 30 days are put through them, so you see what would have gone without asking.

Whatever goes out in your name, costs money, deletes or publishes becomes a proposal. Finance and Delete and publish can never be loosened. An unknown tool counts as Send. A click in the browser is classified by the element it hits, not by what the bot says. See Approvals and rules.

A bot can never approve. The closest it gets is a confirmation card you have to click.

At most one execution

The daemon, not the agent, carries out what you approve, and exactly the content you saw or edited:

• The transition from pending to executing can only happen once. A proposal that has already been decided is refused: "the proposal has already been decided".
• If the daemon stops during an execution, the proposal becomes uncertain at the next start, with the text "The daemon stopped while carrying it out. Check whether it happened.". It is never retried on its own.
• If the agent makes the same proposal again after a restart, it does not become a new proposal. The agent is told that it is done, uncertain or rejected.

The ledger

Every call that changes something is written to the run's ledger before it is carried out, with a key that is the SHA-256 of the tool and the arguments (keys sorted). The same call again in the same run gets the stored result. While the first call is still running, the second is refused. Reading is exempt. For the browser, the state of the page is part of the key, so "Next" twice is two clicks, but "Send" twice on the same page is one.

scripts/kill-matrix/run.py crashes the daemon at every dangerous step and the agent in the middle of a turn, and checks that nothing has been sent twice. See Development.

The audit log

audit_log gets a row for every tool call, every decision, every execution and every connection. It can only grow:

• Triggers in SQLite refuse UPDATE and DELETE.
• Every row has prev_hash and hash, a SHA-256 of the previous hash and the row's fields. A change is detected even if the triggers have been removed.

huskarld verify-audit

prints "N entries, chain intact", or "the audit log is broken at entry ". The command reads the database directly and does not need the daemon.

Logins and keys

• Services (Gmail, Outlook, Teams, GitHub, Elyra Workspace, Félagi) live in the Keychain under no.huskarl.google, no.huskarl.microsoft, no.huskarl.teams, no.huskarl.github, no.huskarl.workspace, no.huskarl.felagi (the daemon token) and no.huskarl.felagi-api (your personal Félagi token). Only the daemon reads them, to call the service itself. They never end up with an agent, in a prompt or in the database.
• Model keys are not stored by Huskarl. Elyra's login is yours, linked in. Claude Code and Grok Build have their own logins for Huskarl, in ~/.huskarl/agents, made and read by the agents themselves.
• Websites: logins live in the bot's browser profile. Password fields are never filled by the bot. You type the password yourself with Take over.

Locally on the machine

• ~/.huskarl and ~/.huskarl/run have mode 0700, and the socket 0600.
• The daemon also checks that whoever connects to the socket is the same user. Others are refused and logged.
• Webhooks listen only on 127.0.0.1. The 32-character token is the key.
• Phone notifications: the topic on ntfy is the key. Only full proposal ids are accepted.
• Apple's model runs on the Mac, in huskarl-local beside the daemon. It only suggests bots and shortens notifications; it gets no tools, and nothing it reads leaves the machine. HUSKARL_LOCAL_MODEL=off or ⌘, → General turns it off.
• Siri asks and reads out, through huskarld status and huskarld ask. It cannot approve: what a bot proposes from Siri waits for you like anything else.
• The microphone in the chat box (huskarl-listen beside the app) turns speech into text on the device only, and only into the field: nothing is sent until you press Enter, and nothing is approved by voice.
• When you show the bot how, what goes in a password, code or card field is never written down, nor an address's query.
• The licence: activating and renewing send elyracode.com the key, a hash of the Mac's hardware id, the Mac's name and the version, nothing about the bots. The answer is checked against the shop's Ed25519 public key in the app; a release build takes no other key. No plan only ever turns the bots to rehearsal: approval, the audit log and the data are never locked.

The browser

The bot's Chrome is started by the daemon. It does not run in Seatbelt and not behind the egress proxy. What keeps it in place is:

• the domain guard: every document request (navigation, redirect, frame) is stopped and only let through to the bot's websites
• that clicks that send, pay or delete wait for approval
• that the bot sees and does nothing while you are in control.

Resources an allowed page fetches itself, such as images, scripts and API calls, are not checked against the list. A page on an allowed website can therefore talk to other hosts, as it would in your own browser.

Red team

Deterministic. Gateway tests play the agent as attacker. They hold whatever the model (phase-2.md):

• Forged tool names and revoked or empty tokens are refused.
• Under a domain rule, none of these get through: kari@acme.no <boss@evil.example>, Cyrillic о in the domain, comma-separated recipients and acme.no.evil.example.
• Outside text cannot forge the end of the wrapping.
• 50 sends become 50 proposals and no mail.

Against a real model. scripts/red-team/run.py runs seven cases against Elyra with the user's default model: six attacks and one control. Run in phase 2 for $0.18 in total:

The gateway would have stopped any send regardless. The corpus shows that the model did not try either. Injection through web pages and attacks over several turns are not covered by the corpus yet.

Not yet

• Isolation in a VM instead of Seatbelt.
• A domain guard for all the resources a page fetches, and the browser in a sandbox.
• The daemon as a helper app with its own identity for system notifications.