Metadata-Version: 2.4
Name: custodian-talaria
Version: 0.2.0
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.

The name comes from Hermes' winged sandals. The software is deliberately
Hermes-specific. Codex has its own adapter,
[Custodian Codex Guard](https://github.com/KeyArgo/custodian-codex-guard)
is the parallel adapter for Codex and is installed separately.

## What Talaria adds

[Custodian Hermes Guard](https://github.com/KeyArgo/custodian-hermes-guard)
provides the narrow enforcement hooks. Talaria builds the product around them:

- a readable policy file for tools, paths, privacy, spending, and approvals;
- a local dashboard for policy, denial history, and vault metadata;
- Paladin-backed credentials that stay out of prompts and configuration;
- session capsules that preserve goals, limits, budgets, and action history
  outside the model;
- governed skill execution with pre-action checks and post-action redaction.

Talaria and Hermes Guard share one canonical runtime. The plugin path and the
brokered execution path do not maintain competing policy engines.

## Install

Version 0.2.0 is available as a GitHub release.

Install from PyPI:

```bash
pipx install "custodian-talaria[dashboard]"
talaria setup
talaria doctor
```

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, preserves existing policy, and
enables it through the Hermes CLI when available. `doctor` sends benign,
forbidden, redaction, and receipt-chain probes through the real runtime.

## One policy file

The default policy lives at `~/.talaria/policy.yaml`:

```yaml
version: "1"

operator:
  mode: open_notify
  approval_wait_seconds: 300

tools:
  forbid: [stripe-payout]

paths:
  forbid: ["~/.ssh", "~/.aws", "~/.gnupg"]
  forbid_globs: ["*.env", "*.pem", "id_rsa"]
  # allow: ["~/projects/hermes-workspace"]

privacy:
  redact: [email, phone, ssn, card]

money:
  max_per_minute: 6
  duplicate_window_s: 600

log_denials: true
```

This is enforcement, not advice in a system prompt. The model cannot persuade
a path fence to ignore a forbidden directory. Mandatory guards for
self-protection, prompt injection, and secret leakage cannot be disabled by
policy.

## 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. If the tool, arguments, workspace, requester, or policy
changes, the approval does not apply.

Once the operator approves, Hermes Guard resumes the exact call. You do not
need to return to the agent conversation and ask it to retry.

## Credentials without prompt exposure

Talaria exposes the Paladin broker through its own CLI:

```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. Paladin materializes the
value only for the governed child process and records the access without
placing the secret in the receipt.

## The local control surface

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

## Release status

The 0.2.0 release has passed the full source suite, filtered artifact tests,
clean-wheel installation, and independent Linux and Windows qualification.
macOS qualification remains pending.

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)
