Safe invoicing for Hermes Agent. Forward a client's message, approve the draft, get paid, all from the chat you already use. Built for freelancers, indie developers, AI consultants and agencies who bill clients.
Watch the 70-second demo: real Telegram, terminal and dashboard footage.
Agents that handle money are a new target for invoice scams. Obol puts an approval in front of every invoice Hermes sends, and catches the tricks that hit invoicing: lookalike addresses, impersonated clients, instructions hidden in forwarded messages, duplicates and quiet edits to the record. It does not prevent all fraud; the limits are spelled out below.
Client: "Loved the new site! Send the invoice: $2,000 build + $400 revisions, due in 14 days."
You: (forward it to Hermes)
Hermes: Proposed invoice: Acme Studio · $2,400.00 · due in 14 days [Allow once] [Deny]
You: Allow once
Hermes: Sent. Payment link: https://…
You: Have they paid?
Hermes: Yes, paid in full today.
Demo (70 s): watch on X · Install: hermes plugins install ueddy/obol · Listed in the official plugin catalog
| Draft from a message | Forward a client's message from any chat; Hermes extracts who to bill, line items, total and due date with your own model. Nothing is created yet. |
| Approve every invoice | Creating, sending, reminding and voiding each ask you first, with the amount, recipient and risk checks in the prompt. "Always" never carries over to the next invoice. |
| Get paid | Your client gets a hosted payment link and pays by card. Ask "have they paid?" and Hermes checks. |
| See everything | /invoices shows paid, open and overdue in any chat; the dashboard adds an Invoices table and a Security view. |
| Chase overdue | An optional weekly report of who to chase. It never sends anything on its own. |
| Check | What happens |
|---|---|
| Injected instructions | Forwarded messages are scanned for instructions to the assistant, including hidden (zero-width, invisible, HTML comments), encoded (base64, URL, hex) and non-English ones. A message can never choose who gets paid. |
| Lookalike addresses | A recipient domain that imitates one you've billed (acrnestudio vs acmestudio) is flagged. |
| Impersonation | A known client at a domain you've never billed them at is flagged. |
| Duplicates, odd amounts, changed details | Same amount recently, far above the client's average, or contact details changed just before billing. |
| Fraud risk and disputes | After payment, the provider's fraud-risk rating and any dispute are shown. |
| Live keys locked | Live keys are refused unless you turn live mode on. |
| Scheduled runs blocked | Unattended (cron) runs can never send an invoice. |
| Tamper-evident logs | Activity and security logs are hash-chained; hermes obol doctor detects edits. |
Every check is backed by tests; see the threat model.
| Surface | Approval | /invoices |
|---|---|---|
| Telegram | buttons | ✓ |
buttons (Cloud API) or typed /approve |
✓ | |
| Slack | buttons | ✓ (also /hermes invoices) |
typed /approve |
✓ | |
| Terminal | approval panel | ✓ |
tests/test_gateways.py drives each surface through Hermes's real gateway code: tools enabled, approval asked in
that chat (deny sends nothing, approve sends), and /invoices dispatched. Telegram was also run live end to end
with a real bot for the demo.
| Provider | Status |
|---|---|
| Stripe | Supported |
| Bank transfer with PDF invoices | Supported: no provider account, no network |
More providers planned. The approvals, scam checks and logs sit in front of the provider and don't depend on it.
Bank-transfer mode. Set provider: bank_transfer and your bank details. Obol keeps the invoices itself:
approving an invoice issues it with a number (INV-0001), a due date and a PDF carrying your bank details and the
invoice number as the payment reference. You send the PDF yourself; when the money lands, say so and Obol records
it with obol_mark_paid (approved like every other write). Every check, /invoices and the dashboard work the
same, and if your own payout details change, the next invoice's approval says so.
-
Get a test secret key (
sk_test_…) from a free Stripe account in test mode. Skip this for bank-transfer mode, which needs no key. -
Install and check:
hermes plugins install ueddy/obol hermes plugins enable obol hermes config set STRIPE_API_KEY sk_test_… # Stripe mode only hermes obol doctor # key mode, provider reachable, log integrity
-
Fill the test account with sample clients (about 40 seconds; test keys only, re-run anytime):
hermes obol demo
It creates paid, open and overdue invoices with real past dates and prints four things to try: forward a client's message, "have they paid?", a lookalike-address scam, and paying with test card
4242 4242 4242 4242.
No Stripe account? Use bank-transfer mode instead (see Configure); hermes obol doctor then
checks your bank details.
Requires Hermes Agent 0.22+. No extra Python dependencies.
Out of the box Obol refuses live Stripe keys (sk_live_…, rk_live_…), both in the provider client and again in
the approval hook. Once you turn live mode on, it runs exactly the same code as test mode: the same Stripe calls,
the same approval prompts, the same scam checks. Bank-transfer mode needs no Stripe key, so none of this applies
to it.
-
Activate your Stripe account. Stripe won't accept live invoices until the account is activated (business details and a payout bank account). That happens on Stripe's side, not in Obol.
-
Use a restricted key. A restricted key (
rk_live_…) is safer than a full secret key. Create one in the Stripe dashboard with only what Obol uses:Resource Access Customers Write Invoices (includes invoice items) Write Charges Read (fraud-risk level on paid invoices) Disputes Read Events Read (recent contact or payment-detail changes) -
Set the key and allow live mode:
hermes config set STRIPE_API_KEY rk_live_… hermes config set plugins.entries.obol.settings.allow_live true hermes obol doctor # should report live mode and Stripe reachable
-
Do one small real run before you rely on it. Send yourself a small real invoice (for example $1 to your own email), pay it, then void it or refund it in the Stripe dashboard. Obol's live path is the same code as test mode, but the automated suite (
tests/test_stripe_live.py) only runs against test keys, so this is the check that confirms your account and key work end to end.
In live mode, Stripe emails your client for real. In test mode, sending only produces a payment link. With a live key, approving a send or a reminder makes Stripe email the actual customer, so one approval puts a real email in front of a real person. The approval prompt says so too; read the recipient before you approve.
Two things stay test-only on purpose: hermes obol demo refuses anything but a test key, and syncing invoices from
Stripe test clocks only exists in test mode.
| Check | How |
|---|---|
| Try it in two minutes | hermes obol demo with a Stripe test key: sample clients, then four prompts to try |
| Installs cleanly | hermes plugins validate . --install-deps && hermes plugins doctor . --ci → 8 tools, 1 hook, install scan safe |
| Tests | python -m pytest: 231 tests, no keys needed (unit, adversarial, recorded real responses, gateway, Hermes integration) |
| Claims are proven | tests/test_readme_claims.py fails if any test named in this README doesn't exist |
| Real, not mocked | live test-mode suite (tests/test_stripe_live.py), real-model intake suite (tests/test_intake_live.py), recorded real responses, live Telegram run |
| More than a skill | tools, an approval hook, structured extraction via ctx.llm, dashboard tab + API, slash command, CLI, automation blueprint, skill |
Each row is an attack that hits invoicing in practice, how Obol responds, and the tests that prove it.
tests/test_readme_claims.py fails if any test named here doesn't exist.
| # | Attack | How Obol defends | Proven by |
|---|---|---|---|
| T1 | Prompt injection in a forwarded message (a "note to the assistant" telling it to drop its rules, skip approval and bill billing@attacker.example) | A deterministic detector (no model involved) scans every forwarded message. Instructions are flagged, shown in the reply, carried into the approval prompt and logged. The message can never choose the recipient: Obol withholds an address that came from it unless it's the one already on file for that client. Drafting never creates or sends anything. | tests/test_security.py::test_direct_injection_is_high, tests/test_intake.py::test_injected_message_never_picks_the_recipient, tests/test_intake.py::test_injection_findings_carry_into_the_approval_prompt, tests/test_hermes_integration.py::test_injection_and_lookalike_reach_the_approval_prompt_and_security_log |
| T2 | Hidden injection (zero-width characters, bidi overrides, invisible Unicode tag characters, HTML comments, full-width letters) | Text is normalised (NFKC, invisible characters removed, tag characters decoded) before scanning; hidden text alone is flagged | tests/test_security.py::test_zero_width_split_words, tests/test_security.py::test_unicode_tag_smuggling, tests/test_security.py::test_html_comment, tests/test_security.py::test_bidi_override_and_fullwidth, tests/test_security.py::test_hidden_text_without_instructions_is_medium |
| T3 | Multilingual injection (Spanish, French, German, Portuguese, Italian, Chinese, Japanese, Russian, Arabic) | Patterns for each language | tests/test_security.py::test_multilingual_injection |
| T4 | Encoded injection (base64, URL-encoding, hex escapes) | Encoded blobs are decoded and scanned too | tests/test_security.py::test_base64_payload, tests/test_security.py::test_url_encoded_payload, tests/test_security.py::test_hex_escaped_payload |
| T5 | Lookalike domain (acrnestudio vs acmestudio, a Cyrillic а, northw1nd, .co vs .com, a known name plus "-billing") | The recipient's domain is compared with every domain you've billed: homoglyph skeletons, 1–2 character edits, the same name on another TLD, a known name plus extra words | tests/test_security.py::test_lookalikes_are_caught, tests/test_security.py::test_lookalike_finding_names_the_real_domain |
| T6 | Impersonation: a known client "writes from a new address" | A client name you've billed before, at a domain you've never used for them, is flagged (a new mailbox at their usual domain isn't) | tests/test_risk.py::test_same_name_new_email, tests/test_intake.py::test_changed_email_for_known_client_warns |
| T7 | Account takeover: the client's email or payment details changed at the provider just before you bill | Recent changes to the customer's email or payment details are flagged | tests/test_risk.py::test_stripe_customer_updated_event, tests/test_risk.py::test_old_or_irrelevant_events_ignored |
| T8 | Agent acting without consent (a fooled or overeager model creating, sending, reminding or voiding) | Every invoice write goes through Hermes's approval prompt, drafts included; there's no setting to turn it off | tests/test_gate.py::test_every_write_asks_including_drafts, tests/test_hermes_integration.py::test_approval_gate_directives |
| T9 | One "always" approval reused for later invoices | Every approval has its own rule key, so "always" can't carry over | tests/test_gate.py::test_rule_key_is_unique_per_call |
| T10 | Unattended runs auto-approving writes (cron with approvals.cron_mode) |
Obol blocks every write during cron, and fails closed if it can't tell | tests/test_gate.py::test_unattended_runs_are_blocked_cleanly, tests/test_hermes_integration.py::test_cron_detection_fails_closed |
| T11 | Live key used by mistake | Live keys are refused in the hook and in the provider client unless allow_live: true |
tests/test_gate.py::test_live_key_blocked_unless_allowed, tests/test_stripe_client.py::test_client_refuses_bad_keys, tests/test_hermes_integration.py::test_live_key_blocked_by_hook |
| T12 | Double billing (a duplicate invoice, or a retry after a timeout) | Duplicate check in the approval prompt; every write carries an idempotency key reused across retries | tests/test_risk.py::test_duplicate_within_window, tests/test_stripe_client.py::test_retries_5xx_with_same_idempotency_key, tests/test_risk.py::test_sees_invoices_made_outside_obol |
| T13 | Inflated or fat-fingered amount | Flags amounts far above the client's average | tests/test_risk.py::test_unusual_amount_needs_history |
| T14 | Risky or disputed payment | The provider's fraud-risk level and any dispute on paid invoices are read (read-only) and surfaced; disputes are rechecked for 120 days | tests/test_payment_risk.py::test_elevated_radar_risk_is_flagged, tests/test_payment_risk.py::test_dispute_found_on_a_later_sync_once, tests/test_payment_risk.py::test_payment_checks_are_read_only |
| T15 | Quiet edits to the record (rewriting who an invoice was sent to, deleting an entry) | Activity and security logs are hash-chained; hermes obol doctor and the Security view verify the chain and detect edits, deletions, reordering and truncation |
tests/test_activity_log.py::test_edited_entry_is_detected, tests/test_activity_log.py::test_deleted_middle_entry_is_detected, tests/test_activity_log.py::test_truncated_tail_is_detected, tests/test_hermes_integration.py::test_doctor_reports_intact_then_tampered_log |
| T16 | Key leakage through errors or output | Obol reads the provider key only via Hermes's secret route; anything key-shaped is scrubbed from provider error messages | tests/test_stripe_client.py::test_key_never_appears_in_errors_or_reprs |
| T17 | A broken check silently hiding the prompt | A failing risk check still shows the approval prompt, marked incomplete; a failing hook blocks the call | tests/test_gate.py::test_flags_shown_and_broken_checks_do_not_hide_prompt, tests/test_risk.py::test_stripe_failures_degrade_to_info |
| T18 | Hostile input (malformed invoice ids, path tricks, bad amounts) | Validated locally before any provider call | tests/test_service.py::test_bad_invoice_id_rejected_locally, tests/test_service.py::test_validation_happens_before_any_call |
| T19 | Obol reaching beyond invoicing | Obol's only hook gates its own invoice writes; other plugins' tools pass through untouched, and it registers no observers | tests/test_hermes_integration.py::test_other_plugins_tools_are_left_alone |
| T20 | Your own payout details swapped (someone edits your bank account in Obol's settings so clients pay them) | In bank-transfer mode, a change to your payout details is flagged HIGH in the next invoice's approval with the new account's last four digits; only a fingerprint is logged, never the number. Marking paid is a write that needs approval and is refused in scheduled runs | tests/test_bank.py::test_changed_payout_details_are_flagged_on_the_next_invoice, tests/test_bank.py::test_approval_prompt_says_bank_transfer |
No noise in normal use. The checks stay quiet on everyday client messages ("send the invoice to
ap@…", "please ignore my previous email, the amount is $500", "invoice us right away") and on the
demo's own client list: tests/test_security.py::test_normal_messages_raise_nothing,
tests/test_security.py::test_no_false_positives_across_demo_clients,
tests/test_security.py::test_unrelated_domains_are_quiet,
tests/test_payment_risk.py::test_normal_payment_records_radar_level_without_noise.
- You approving something you shouldn't. Obol shows the facts and flags; the decision is yours.
- Approvals switched off. With YOLO mode or
approvals.mode: off, Hermes approves everything, Obol's prompts included. Live-key and scheduled-run refusals still apply. - Injection it has never seen. Detection is pattern-based; new phrasings, other languages or instructions in images can slip through. The recipient rule and the approval prompt don't depend on detection.
- Lookalikes of clients you haven't billed yet. Comparisons use Obol's local history only.
- Someone impersonating you to your client. An invoice sent outside Obol never reaches it.
- A compromised provider account or key.
- An attacker who can rewrite the whole database. The chain catches edits that don't recompute it;
hermes obol doctorprints the head hash so you can keep a copy elsewhere. - Real-time alerts. Obol polls (no webhooks), so payments and disputes appear on the next sync.
Settings live under plugins.entries.obol.settings (Hermes Desktop shows them as a form).
| Setting | Default | Meaning |
|---|---|---|
allow_live |
false |
Must be true before a live key is accepted (see Going live) |
default_currency |
usd |
Currency when a request doesn't name one |
default_days_until_due |
14 |
Payment terms for new invoices |
risk_duplicate_window_days |
30 |
Same customer and amount within this many days (0 = off) |
risk_amount_multiplier |
3.0 |
Flag amounts above this multiple of the client's average (0 = off) |
risk_amount_min_history |
3 |
Invoices needed before the amount check applies |
risk_contact_change_days |
14 |
Contact details changed this recently (max 30, 0 = off) |
risk_lookalike_domains |
true |
Flag domains that imitate one you've billed |
risk_impersonation |
true |
Flag a known client at a new domain |
provider |
stripe |
bank_transfer for PDF invoices paid by bank transfer (no provider account) |
business_name |
Shown at the top of bank-transfer PDFs | |
bank_account_name, bank_account_number |
Required in bank-transfer mode | |
bank_name, bank_routing |
Optional: bank, and routing / sort code / IBAN / SWIFT |
Injection detection is always on.
- Network: the payment provider's API only (today
api.stripe.com), over HTTPS: when a tool,/invoices syncorhermes obol doctor|syncruns; in the approval hook before a write (5-second timeout); during sync for fraud-risk and dispute reads (read-only); every 45 s while the dashboard tab is open. Polling only; no webhooks, no open ports. In bank-transfer mode Obol makes no network calls at all. - Your model:
obol_draft_from_messagesends the forwarded message to the model Hermes is configured to use, throughctx.llm. - Emails: sending and reminding make the payment provider email your client. In bank-transfer mode nobody is emailed; PDFs are written to
<HERMES_HOME>/plugin-data/obol/invoices/. - Credentials:
STRIPE_API_KEY(optional, Stripe mode only; install doesn't ask for it), read only through Hermes's secret route; never logged or stored. Without it, Stripe-mode tools answer "Stripe key not set" and do nothing. - Local data:
<HERMES_HOME>/plugin-data/obol/data.db: cached invoice metadata, risk findings, and hash-chained activity and security logs (forwarded message text is not stored). Delete the file to clear it. Bank-transfer details (account name, number, bank, routing) are plugin settings, stored in plain text in Hermes'sconfig.yaml. The full number appears only there and on the PDFs: Obol's logs and database hold a fingerprint of the details and the account's last four digits, never the number itself. - No telemetry, shell commands, background processes or self-updating code.
git clone https://github.com/UEddy/Obol && cd Obol
python -m pytest # no keys needed
/path/to/hermes-venv/bin/python -m pytest # also runs Hermes integration and gateway testsSTRIPE_API_KEY=sk_test_…also runstests/test_stripe_live.py(refuses live keys, cleans up after itself).OBOL_LIVE_LLM=1 OBOL_LIVE_HERMES_HOME=…runstests/test_intake_live.pyagainst a real model and records the results fortests/test_intake_recorded.py.
__init__.py registration: tools, approval hook, /invoices, CLI, blueprint, skill
schemas.py tool schemas
src/obol_lib/ provider client, invoice service, approval policy, risk checks,
injection + lookalike detection, message intake, SQLite store with hash-chained logs
dashboard/ Invoices and Security views (plugin SDK, no build step) and their API
skills/invoicing/ the obol:invoicing skill
tests/ 234 tests
- Reading bank-transfer payments from a bank feed instead of marking them paid by hand.
MIT