Talaria

Hermes gets hands. Talaria gives them boundaries.

Talaria is the governed runtime and operator experience for Hermes Agent. It connects Hermes to Custodian's policy kernel and Paladin credential broker, then gives you one place to see what the agent attempted, what ran, what was blocked, and why.

Install runs open by default — nothing is blocked until you decide it should be, and the one exception (SSH keys, cloud credentials, secret files) is disclosed to you at install time, not left implicit. One command locks it down; one command reopens it. Talaria never leaves you guessing which state you're in — talaria status, talaria doctor, and every action's own notice say so plainly.

The name comes from Hermes' winged sandals. The software is deliberately Hermes-specific — Custodian Codex Guard is the parallel adapter for Codex and is installed separately.

Install

pipx install "custodian-talaria[dashboard]"
talaria setup
talaria demo

On Linux distributions that enforce PEP 668, use pipx or a virtual environment. Do not use --break-system-packages.

setup installs the packaged Hermes plugin and preserves any existing policy. demo is the fastest way to see what you just installed — it runs entirely in a throwaway workspace and never touches your real ~/.talaria.

See it before you trust it

talaria demo

walks through the real decision engine, narrated, with nothing pre-configured and nothing actually executed:

1. a benign write, in the shipped default (open) mode — allowed
2. a read of an SSH key — blocked, in every mode, open or locked
3. a destructive shell command, still open — allowed, with a notice telling you it crossed an open gate
4. talaria policy lockdown — the one command that changes the rest
5. the exact same destructive command, now protected — held for approval
6. the operator approves it — the call resumes, once, for that exact digest
7. the receipt trail — every step above, authenticated, no secrets or prompts inside, chain-verified in front of you

Run it yourself, watch a ~35s recording of it (asciinema play docs/demo.cast from a source checkout, or agg docs/demo.cast demo.gif to convert it), or read the transcript below — it's exactly what the command prints:

Policy: OPEN (default) — money, credential, destructive, production,
network, and governance actions run automatically with a notice;
nothing else is blocked yet. ...

[1] a benign write, in the shipped default (open) mode
    -> ALLOWED (write): write action is within the workspace safety boundary

[2] read an SSH key — forbidden in every mode, open or locked
    -> BLOCKED (read): path '...' is inside a forbidden location ...

[3] a destructive shell command, still in open mode
    -> ALLOWED (destructive): open gate observed destructive action
    notice: Talaria allowed this destructive. destructive controls are open.

[4] lock it down — one command: talaria policy lockdown
    Policy: LOCKED DOWN — ... need your approval before they run.

[5] the exact same destructive command, now protected
    -> NEEDS APPROVAL (destructive): destructive actions require explicit
       human approval ...

[6] operator approves it (approval 4cae699d...)
    -> ALLOWED (destructive): exact single-use approval consumed

[7] the receipt trail — every step above, authenticated
    5 receipts, chain verified, no secrets or prompts inside

Open by default, locked down on demand

talaria policy status      # what's true right now
talaria policy lockdown    # require approval for gated actions
talaria policy monitor     # back to open, with notices

The gated classes are money, credential, destructive, production, network, and governance actions. In open mode they run automatically and Talaria tells you when one did, and how to close it — you are never left assuming protection you don't have. Path rules (SSH keys, cloud credentials, secret files) and three kernel-grade guards (secret-leak, prompt-injection, self-protection) are enforced in every mode; they're the one thing "open" does not mean "off." talaria status and talaria doctor state the current posture in the first line of their output, every time.

Three recipes

Each one states what it does, how to reverse it, and what it does not protect against. None require you to touch policy.yaml by hand, though you can — the CLI is a thin, reversible layer over the same file.

1. Stop the agent from reading SSH keys or secret files

This is already true the moment you install — no command needed:

talaria demo   # step [2] shows the denial live

~/.ssh, ~/.aws, ~/.gnupg, and glob patterns like *.pem/id_rsa/*.key are forbidden by default, in open mode and locked mode alike. To narrow or widen the list, edit paths.forbid / paths.forbid_globs in ~/.talaria/policy.yaml, then confirm with talaria log after the agent actually attempts the path (talaria doctor re-probes the built-in SSH-key case on every run, but only that one — a custom addition to the list needs its own real attempt to verify). Reverse it by removing the entry from the list — there is no separate on/off switch, the list itself is the policy.

What this protects: the agent's own tool calls, mechanically, regardless of what the model was told to do. What it doesn't: a path outside the forbidden list that still happens to contain a credential — that's a secret-leak concern (also always on), not a path-fence one, and is a different guard with a different blind spot (see "What this does not do").

2. Require approval before a destructive shell command runs

talaria policy lockdown

From then on, a shell command matching a destructive pattern (rm, rmdir, shred, git reset --hard, git clean -f, and similar) is held rather than run:

Talaria needs your approval for this destructive action.

Approve or deny it from the operator terminal (custodian-hermes-guard is installed alongside Talaria):

custodian-hermes approve latest --operator you
custodian-hermes deny latest --operator you

Approving resumes the exact call — same tool, same arguments, same workspace — not a fresh retry the model could have changed; a denial is final for that digest. Reverse the lockdown itself with talaria policy monitor. This does not sandbox the shell — a destructive command that doesn't match the pattern list, or one run outside Talaria's mediation entirely, is not caught by this recipe.

3. Use a brokered API credential without it ever touching the prompt

talaria vault add stripe_sk --env-var STRIPE_SECRET_KEY
talaria vault list
talaria vault exec --with stripe_sk -- ./charge.py

The agent receives a paladin://stripe_sk reference, never the value. Paladin materializes the real secret only inside the governed child process and records the access in a receipt that never contains the secret itself. Reverse it with talaria vault rm stripe_sk. This does not protect a credential the agent already holds some other way (an env var it can already read, a config file outside the forbidden-path list) — brokering only helps for values that go through the vault in the first place.

Approvals that resume

In protected mode, Talaria holds a consequential action while it waits for an authenticated Custodian approval. The approval is single-use and bound to the original digest — tool, arguments, workspace, requester, and policy version all have to match, or it doesn't apply. Once approved, Hermes Guard resumes the exact call; you never return to the agent conversation and ask it to retry.

The local control surface

talaria status
talaria doctor
talaria log
talaria log verify
talaria repair
talaria disable
talaria uninstall

For the web interface:

talaria dashboard

The dashboard binds to 127.0.0.1:8765 by default and uses a per-launch token. It shows denial history, policy controls, and vault metadata. Secret values do not go to the browser.

Governed sessions

For work that needs execution rather than hook-only mediation:

talaria init hermes-session.yaml --goal "keep the homelab healthy"
talaria adapters list
talaria session status hermes-session.capsule.json

The session bridge applies guard adapters, authority bands, kill-switch state, workspace and network limits, Paladin credential grants, result redaction, and capsule recording around each invocation.

Hermes proposes a skill call
        |
        v
pre-action guards and policy
        |
        v
authority, budget, and kill-switch decision
        |
        v
Paladin resolves permitted credentials for the child process
        |
        v
skill executes
        |
        v
post-action redaction and capsule receipt

Compatibility

CI exercises Ubuntu, Windows, and macOS runners against Python 3.11, 3.12, and 3.13 on every change (.github/workflows/ci.yml), using only free GitHub-hosted runners — no paid CI is used. Talaria itself is tested against the Hermes plugin contract documented at hermes-agent/plugins; it does not pin to a specific Hermes release.

What this does not do

Talaria mediates the calls the agent makes through Hermes's plugin hook. It does not replace operating-system sandboxing, does not inspect network traffic Hermes itself doesn't route through a mediated tool call, and its secret-leak guard scans tool output for known credential shapes — it is not a general data-loss-prevention system. Read SECURITY.md for the full model, including the self-approval bug found and fixed during development.

Release status

0.2.0 shipped the governed runtime, approvals, and receipt chain, and has passed the full source suite, filtered artifact tests, clean-wheel installation, and independent Linux and Windows qualification. macOS qualification remains pending. 0.2.1 adds the open-by-default demo, README recipes, and talaria policy on top of that, verified the same way.

Talaria is alpha software and has not received a third-party security audit. It is defense in depth, not an operating-system sandbox. Read SECURITY.md before using it for consequential actions.

Links

• Source
• Hermes Guard
• Custodian Kernel
• Documentation
• Security policy
• Contributing