Mythos Sentinel

Local-first runtime firewall for wallet-enabled AI agents, MCP tools, and x402/Base payments.

Agents are starting to discover paid APIs and pay over HTTP. Sentinel sits before those payments and answers the question raw wallets and discovery layers do not fully answer:

Should this agent be allowed to spend this amount on this endpoint right now?

Agent / MCP client / wallet-enabled workflow
        ↓
Mythos Sentinel
        ↓
policy · budget · unknown-domain rules · RouteScore signal
        ↓
allow · approval_required · block · receipt

Why Sentinel?

Tool type	What it does	What Sentinel adds
Agent frameworks	Run tasks and call tools	Spend/control layer before risky actions
MCP clients	Connect agents to tools	Runtime proxy and policy enforcement
x402 APIs	Let agents pay services	Budget, trust, receipts, and fallback routing
Wallet permissions	Limit raw spend	Context-aware allow / approval / block decisions
API marketplaces	Help agents discover services	Local reliability scoring and routing decisions

Why this exists

x402/Bazaar-style discovery makes it easier for agents to find and pay APIs. That creates a new problem: agents can spend quickly, but they still need budgets, trust signals, logs, and approval rules.

Sentinel is the local control layer around that behavior:

• Can this agent spend on this domain?
• Is this amount safe for an unknown API?
• Does RouteScore say this endpoint is reliable enough?
• Did the action produce an audit trail?
• Should the human approve before payment?

Core features

Feature	What it does
Adaptive x402/Base spend guard	Enforces trusted, known, unknown, denied, budget, and RouteScore-based decisions against a persistent local spend ledger.
RouteScore catalog + routing	Scores seed, custom, and Bazaar-imported paid agent APIs, then recommends selected services and fallback routes.
Fallback routing primitives	Plans and executes fallback attempts through caller-provided executors so agents can retry safer alternatives when a provider fails.
x402 receipt ingestion	Normalizes sanitized x402 payment receipts, tracks settlement status, and summarizes observed spend without storing prompts or responses.
Opt-in local telemetry	Stores sanitized local endpoint events only after the user enables it. No prompts, responses, secrets, private files, or wallet balances.
Passive reliability scoring	Uses proxied-call success/failure, latency, schema, and price-match signals to improve RouteScore locally.
Runtime MCP proxy	Puts Sentinel in the call path of upstream MCP tools: recognized payment, shell, file, and network intent is gated, and unrecognized calls follow a configurable defaultAction (see THREAT_MODEL.md).
Local spend ledger	Sentinel's own persistent record of daily spend. Budget enforcement reads max(ledger, caller-reported), so an agent reporting zero cannot reset its budget.
Signed spend mandates	EIP-712 signed spending envelopes (scope, caps, expiry). Enforced against the ledger's lifetime per-mandate totals; with requireMandate, uncovered payments are held for approval.
On-chain attestation	attest bundles local receipts into a merkle-committed, optionally signed record and can post it to Base via EAS — tamper-evident, timestamped proof your records existed.
x402 service directory	directory build exports a sanitized, domain-level public directory of observed service behavior (settle rates, volume, RouteScore). Opt-in, reviewed, never auto-uploaded.
Scanner and guards	Finds risky instructions and checks command, file, network, and payment actions before execution.
Receipts	Captures before/after workspace hashes and verifies agent work.
Local dashboard	A premium local control room for policy, RouteScore, telemetry, receipts, and guard tests.
GitHub Action	Runs Sentinel in CI without model keys, wallet keys, or hosted accounts.

Install

npm install -g mythos-sentinel

Or run directly:

npx mythos-sentinel help

Node.js 20+ is required. Sentinel does not require OpenAI, Anthropic, Coinbase, wallet, or private-key access.

Runtime MCP proxy

Direct MCP mode gives agents Sentinel tools to ask for permission. Runtime proxy mode puts Sentinel in the call path of upstream MCP servers: every recognized payment, shell, file, or network intent is gated before forwarding, daily budgets are enforced from Sentinel's own spend ledger, and calls the classifier does not recognize follow mcpProxy.defaultAction (allow by default for compatibility; set approval_required or block to fail closed). Classification is heuristic — read THREAT_MODEL.md for exactly what the proxy does and does not guarantee.

mythos-sentinel proxy

Flow:

Agent -> Mythos Sentinel Proxy -> upstream MCP tools / x402 APIs

Use this mode for wallet-enabled agents, paid x402 APIs, shell tools, file tools, browser tools, and demos that need real enforcement. See docs/RUNTIME_MCP_PROXY.md.

Quick start

Inside the project you want to protect:

mythos-sentinel init --base
mythos-sentinel scan .
mythos-sentinel ui

Check actions before an agent does them:

mythos-sentinel check-command -- "npm install unknown-package"
mythos-sentinel check-file --path .env --operation read
mythos-sentinel check-network --domain api.github.com
mythos-sentinel check-payment --domain api.exa.ai --amount 0.01
mythos-sentinel check-payment --domain fresh-api.example --amount 0.01
mythos-sentinel check-payment --domain fresh-api.example --amount 0.10

List, import, recommend, and route x402 services:

mythos-sentinel routescore categories
mythos-sentinel routescore list
mythos-sentinel routescore import services.yml
mythos-sentinel routescore sync-bazaar --query web_search --limit 20
mythos-sentinel routescore recommend --category web_search --max-price 0.05
mythos-sentinel routescore route --category web_search --max-price 0.05
mythos-sentinel routescore fallback --category web_search --max-price 0.05 --simulate-fail primary

Enable local telemetry and inspect receipt summaries:

mythos-sentinel telemetry enable
mythos-sentinel telemetry status
mythos-sentinel telemetry summary
mythos-sentinel x402-receipt summary

Adaptive payment policy

Default behavior is balanced: agents can explore, but not with unlimited wallet freedom.

{
  "payments": {
    "x402": {
      "enabled": true,
      "strategy": "balanced",
      "maxPerRequestUSDC": 0.25,
      "maxDailyUSDC": 5,
      "requireApprovalAboveUSDC": 0.25,
      "trustedDomains": ["api.coinbase.com", "api.developer.coinbase.com", "api.exa.ai"],
      "deniedDomains": [],
      "unknown": {
        "allowTrial": true,
        "maxPerRequestUSDC": 0.02,
        "maxDailyUSDC": 0.25,
        "requireApprovalAboveUSDC": 0.02
      },
      "routeScore": {
        "autoAllowMinScore": 80,
        "requireApprovalBelowScore": 60,
        "blockBelowScore": 35
      }
    }
  }
}

Decision model:

trusted domain + under budget         -> allow
known service + high RouteScore       -> allow
unknown domain + tiny amount          -> allow trial
unknown domain + larger amount        -> approval_required
low RouteScore / denied / over budget -> block

This avoids the bad tradeoff of either blocking every new API or letting agents freely spend on anything.

RouteScore and fallback routing

RouteScore is not a fake global oracle. It starts with a seed catalog, can import live/custom services, and becomes more valuable when agents route calls through Sentinel and opt into local telemetry.

Data layers:

1. Seed metadata — starter category/domain/endpoint/rough-price metadata.
2. Custom local services — user-imported services.yml / JSON.
3. Optional Bazaar metadata — live public discovery metadata synced into local storage.
4. Local telemetry — opt-in success/failure/latency/price-match observations.
5. x402 receipts — sanitized local payment/settlement records.

Commands:

mythos-sentinel routescore categories
mythos-sentinel routescore list --json
mythos-sentinel routescore import services.yml
mythos-sentinel routescore sync-bazaar --query content_extraction --limit 20
mythos-sentinel routescore recommend --category content_extraction --max-price 0.05 --json
mythos-sentinel routescore route --category content_extraction --max-price 0.05 --json
mythos-sentinel routescore fallback --category content_extraction --max-price 0.05 --simulate-fail primary

Custom service catalog example:

services:
  - name: Custom Search API
    category: web_search
    domain: api.example.com
    endpoint: https://api.example.com/search
    priceUSDC: 0.01
    network: base

See docs/ROUTESCORE.md, docs/FALLBACK_ROUTING.md, and docs/BAZAAR_ADAPTER.md.

Opt-in telemetry and x402 receipts

Telemetry is disabled until the user enables it. It stores sanitized endpoint metadata only and never stores prompts, responses, secrets, private files, private keys, or wallet balances.

mythos-sentinel telemetry enable
mythos-sentinel telemetry status
mythos-sentinel telemetry summary
mythos-sentinel telemetry events --json

x402 receipt ingestion stores sanitized payment proof locally and can feed RouteScore telemetry when telemetry is enabled.

mythos-sentinel x402-receipt ingest --file receipt.json
mythos-sentinel x402-receipt summary
mythos-sentinel x402-receipt list --json

See docs/TELEMETRY.md, docs/PASSIVE_SCORING.md, and docs/X402_RECEIPTS.md.

Local dashboard

Run:

mythos-sentinel ui

For GitHub Codespaces demos:

mythos-sentinel ui --host 0.0.0.0 --port 4317 --demo

The dashboard is local-first. It does not upload repos, secrets, wallet keys, prompts, responses, telemetry, or reports to a hosted Mythos service.

MCP usage

Run the MCP-style server:

mythos-sentinel mcp

Example Cursor/Claude MCP config:

{
  "mcpServers": {
    "mythos-sentinel": {
      "command": "npx",
      "args": ["mythos-sentinel", "mcp"]
    }
  }
}

Exposed tools:

• sentinel_scan_path
• sentinel_check_x402_payment
• sentinel_recommend_x402_service
• sentinel_route_x402_service
• sentinel_list_service_categories
• sentinel_parse_x402_receipt
• sentinel_score_x402_domain
• sentinel_check_command
• sentinel_check_file
• sentinel_check_network
• sentinel_snapshot

Scanner demo

Sentinel detects secrets, risky shell installers, sensitive files, network calls, and policy violations before agent work is trusted.

Receipts

Create an agent work receipt:

mythos-sentinel snapshot . --out .mythos/snapshots/before.json
# Let Codex/Cursor/Claude/your agent work here.
mythos-sentinel scan . --out .mythos/reports/sentinel-report.json
mythos-sentinel receipt \
  --before .mythos/snapshots/before.json \
  --summary "Implemented feature safely" \
  --agent codex \
  --provider openai \
  --tool codex-cli \
  --out mythos-receipt.json
mythos-sentinel verify --receipt mythos-receipt.json

CLI commands

mythos-sentinel init [--base] [--force]
mythos-sentinel scan [path] [--json] [--sarif] [--out report.json] [--fail-on high|critical|none]
mythos-sentinel check-payment --domain api.example.com --amount 0.05 [--daily-spent 1.2] [--route-score 91]
mythos-sentinel check-command -- "shell command"
mythos-sentinel check-file --path .env --operation read|write
mythos-sentinel check-network --domain api.example.com
mythos-sentinel routescore list|categories|recommend|route|fallback [--category web_search] [--max-price 0.05]
mythos-sentinel routescore import services.yml
mythos-sentinel routescore sync-bazaar [--query web_search] [--limit 20]
mythos-sentinel routescore search-bazaar --query browser --limit 10
mythos-sentinel telemetry status|enable|disable|summary|events
mythos-sentinel x402-receipt ingest --file receipt.json
mythos-sentinel x402-receipt summary
mythos-sentinel x402-receipt list
mythos-sentinel snapshot [path] --out before.json
mythos-sentinel receipt --before before.json --summary "task" --agent codex
mythos-sentinel verify --receipt mythos-receipt.json
mythos-sentinel mcp
mythos-sentinel proxy [--policy mythos.policy.json] [--config proxy.json]
mythos-sentinel ui [--host 127.0.0.1] [--port 4317] [--open] [--demo]
mythos-sentinel doctor

Security model

Sentinel is a policy decision engine and scanner. It is not a sandbox, wallet, transaction signer, or guarantee of API quality. It works when agents route risky actions through Sentinel before execution/payment.

For real funds, use least-privilege agent wallets, low spend permissions, testnet rehearsals, separate API credentials, hardware wallets for high-value assets, and human approval for large payments.

Roadmap

• Static agent/skill/MCP/repo scanner
• command, file, network, and x402/Base guards
• adaptive unknown-domain trial policy
• RouteScore seed catalog and recommendation API
• MCP RouteScore tools
• premium local dashboard
• GitHub Action and optional SARIF workflow
• snapshot and agent work receipts
• runtime MCP proxy mode
• opt-in local telemetry store
• passive routed-call reliability scoring
• live Bazaar catalog adapter
• fallback route planning and execution primitives
• expanded service categories
• x402 payment receipt ingestion
• signed provider badges
• optional shared reliability network

License

MIT