Metadata-Version: 2.4
Name: custodian-talaria
Version: 0.2.1
Summary: Talaria — governed, kernel-enforced security for Hermes Agent and NemoClaw
Author-email: InovinLabs <hello@inovinlabs.com>
License-Expression: MIT
Project-URL: Homepage, https://getcustodian.xyz
Project-URL: Repository, https://github.com/KeyArgo/custodian-talaria
Project-URL: Custodian kernel, https://github.com/KeyArgo/custodian-kernel
Project-URL: Issues, https://github.com/KeyArgo/custodian-talaria/issues
Project-URL: Security, https://github.com/KeyArgo/custodian-talaria/blob/main/SECURITY.md
Project-URL: Changelog, https://github.com/KeyArgo/custodian-talaria/blob/main/CHANGELOG.md
Keywords: ai,agent,hermes,security,guardrails,secrets,authority
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: custodian-kernel<0.5,>=0.4.2
Requires-Dist: custodian-hermes-guard<0.2,>=0.1.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: flask>=3.0; extra == "dev"
Provides-Extra: dashboard
Requires-Dist: flask>=3.0; extra == "dashboard"
Dynamic: license-file

# Talaria

### Hermes gets hands. Talaria gives them boundaries.

Talaria is the governed runtime and operator experience for
[Hermes Agent](https://github.com/NousResearch/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](https://github.com/KeyArgo/custodian-codex-guard)
is the parallel adapter for Codex and is installed separately.

## Install

```bash
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

```bash
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:

```text
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

```bash
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:

```bash
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

```bash
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:

```text
Talaria needs your approval for this destructive action.
```

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

```bash
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

```bash
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

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

For the web interface:

```bash
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:

```bash
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.

```text
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](https://github.com/NousResearch/hermes-agent/blob/main/website/docs/user-guide/features/plugins.md);
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](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](SECURITY.md) before using it for consequential actions.

## Links

- [Source](https://github.com/KeyArgo/custodian-talaria)
- [Hermes Guard](https://github.com/KeyArgo/custodian-hermes-guard)
- [Custodian Kernel](https://github.com/KeyArgo/custodian-kernel)
- [Documentation](https://getcustodian.xyz/docs)
- [Security policy](SECURITY.md)
- [Contributing](CONTRIBUTING.md)
