Skip to main content

agentinbox

Block / limit — The approval control plane for consequential agent actions: every agent ask becomes a decision a human can make in seconds — from the terminal, a desktop notification, a CI checkpoint, or a signed webhook. No chat platform required.

OpenSSF Scorecard

Part of the agentic-suite — open-source, harness-agnostic security for AI agents. agentinbox is the human half of the ask-gate: agentpolicy asks, agentinbox answers.

Status

v0.1.0 core is complete through M22 (security close-out); the release is still in development (M24 field tests and M25 release readiness remain). The ask lifecycle, all channels, evidence/audit, operations (M21), and the security packs/scanner (M22) are implemented and tested; the docs (M23) are live. Field tests (M24) and the release (M25) remain, so the PyPI release and the v0.1.0 tag are not yet published — install from source today. See the WBS for the build order and claims and limitations for what is not claimed.

What it does

AI agents are increasingly trusted with actions that cannot be undone — dropping a production table, force-pushing main, sending the customer list to an external endpoint, rotating a live credential. The policy layer (agentpolicy) can already say "a human must decide" — but until now that sentence ended in a harness prompt only one person, in one session, on one machine ever saw. Headless and CI agents got nothing at all.

agentinbox is the missing destination:

  • Decision-ready cards — what the agent wants to do, which policy clause fired, the blast radius, the session so far. An approver with zero context makes the correct call in under 15 seconds (that's an acceptance test, not a slogan).
  • Answer from where you are — terminal/TUI, desktop notification, CI checkpoint, signed webhooks (ntfy/Pushover/Discord recipes). Matrix is next; Slack/Teams are optional adapters. The product is complete with no chat platform at all and works air-gapped.
  • Timeout = deny — the safe default, configurable per action class, with a pre-expiry warning and a rescope hint the agent can act on. No answer in time means the action does not happen.
  • Escalation ladders — unanswered asks route up (buddy → on-call → channel) within the configured window; escalation changes routing, never the deadline.
  • Flood protection — a misbehaving agent cannot spam the inbox: throttling, auto-deny on flood, one event, one digest — the inbox gets quieter under attack, not louder.
  • Evidence-grade audit — every ask/answer/timeout/escalation recorded in an append-only, hash-chained local log and emitted in the agentwatch security-event schema. Full gate history reconstructs per session.
  • Unforgeable answers — an answer is a single-use claim token bound to the exact action identity plus an authenticated principal. Forwarded messages, replayed callbacks, late taps, and "similar" actions change nothing. A model never answers a gate — that's the anti-requirement.

What it is not

No ML in any decision path. No chat-bot decision surface. No harness-side UI replacement. No SaaS. Full list of boundaries in docs/prd/14-non-goals.md.

Compatibility

Harness-agnostic by construction: it consumes the agentpolicy ask contract (ask/1.0 — a small JSON document reachable via HTTP, CLI, or file) and the agentwatch event schema, so any agentic system that can pause for a human can emit an ask. Named adapters make the top surfaces convenient — Claude Code PreToolUse hooks, Codex CLI wrappers, a LangGraph interrupt() reference adapter, CI recipes (GitHub Actions, GitLab, Jenkins, Argo), MCP tool-gating recipes. The honest, per-release compatibility table (field-tested / conformance-tested / documented / not-supported) lives in docs/prd/19-harness-compatibility.md.

Install (from source today)

The package is standalone: no runtime dependencies beyond the Python standard library, no network calls, no external services. Python 3.11–3.13 on POSIX (Windows is not supported in v0.1.0).

git clone https://github.com/agentic-suite/agentsec-agentinbox
cd agentsec-agentinbox
make setup                 # creates .venv and installs the package + dev tools
agentinbox --version       # or: python -m agentinbox --version

agentinbox init            # writes ~/.agentinbox + a commented config.toml
agentinbox doctor          # exit 0 on a healthy install, 4 (fail-closed) otherwise

AGENTINBOX_HOME (or --home) relocates the home directory. A PyPI release (pip install agentsec-agentinbox) lands with the v0.1.0 release (M33).

Quickstart (first approval in under 5 minutes)

The step-tested walkthrough is docs/tutorials/quickstart.md. In short: put your OS user on the roster, then in two terminals:

# terminal 1 (blocks at the gate)
agentinbox ask --exec "echo hello" --timeout 300

# terminal 2
agentinbox inbox
agentinbox answer <ask_id>      # card → a → type run_command
agentinbox report --json        # local-only metrics
agentinbox verify-log           # hash chain

Documentation

License

Apache License 2.0 — see LICENSE.

Metadata

Release files for agentsec-agentinbox 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agentsec-agentinbox 0.1.0
File Size Uploaded Provenance Actions
agentsec_agentinbox-0.1.0.tar.gz 921.2 kB Without provenance Details for agentsec_agentinbox-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agentsec-agentinbox 0.1.0
File Interpreter ABI Platform Actions
agentsec_agentinbox-0.1.0-py3-none-any.whl Python 3 none any Details for agentsec_agentinbox-0.1.0-py3-none-any.whl

Total release size: 1.1 MB

Release files / agentsec_agentinbox-0.1.0.tar.gz

Download URL agentsec_agentinbox-0.1.0.tar.gz
Size 921.2 kB
Tags Source
SHA-256 checksum
How to use checksums
3cd19b337a4c1bd99401ae92db3d7ade791181c5cddfc82920f5cdcd78853432
BLAKE2b-256 checksum
How to use checksums
4fdfceebc0dbc14f539f38064c36f16e317783f1855dcc1d10eccf89d351661f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.5

Release files / agentsec_agentinbox-0.1.0-py3-none-any.whl

Download URL agentsec_agentinbox-0.1.0-py3-none-any.whl
Size 181.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e9e5669f4e93f4f65a39e2cce6d4d5bd46aa8579f4d9b19a65b75acc5544f808
BLAKE2b-256 checksum
How to use checksums
cda2d34b60e90aa86cebc4b4c522a85d05c7b3d8e6338bddbf6df28124f4e20a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.5

Security for agentsec-agentinbox 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page