Why agentboxx
Most agent tooling records what the agent says it did, from inside the agent's own process. agentbox observes from the outside.
| What it gives you | |
|---|---|
| Host-side capture | Output, exit codes and timing are recorded by the host, not reported by the agent. |
| Tamper-evident logs | Every record is hash-chained and HMAC-signed with a key that never enters the sandbox. Edits, deletions and reordering are detected by agentbox verify. |
| State-aware loop detection | A repeated command only counts when the workspace did not change, which separates retrying from making progress. |
| Hint feedback | When the detector fires, a hint is added to the agent's next observation so it can change approach. |
| Hardened sandbox | Docker backend with no network, read-only root filesystem, dropped capabilities, non-root user and resource limits. |
Architecture
| Module | Role |
|---|---|
signer.py |
Hash-chained event log, HMAC signatures, and Ed25519 run receipts |
contract.py |
Task contracts, step/duration/deadline budgets, safe file and command assertions |
bundle.py |
Self-contained signed evidence bundles for offline auditing (agentbox bundle) |
docker_backend.py |
Hardened container sandbox and ephemeral evaluation container |
egress_proxy.py |
Outbound network filtering proxy with connection audit logging |
loop_detector.py |
State-aware repeat, repeated error, no-progress, and cycle detection |
toolcall.py |
First-class MCP and function tool-call recording with payload capping |
executor.py |
Command execution, process-tree termination, workspace hashing |
recorder.py |
Main API: Recorder.run(), record_step(), record_tool_call() |
agent.py |
ReAct-style agent loop that injects detector hints back into observations |
Quick start
Requires Python 3.10+. Docker is optional and used by the sandbox demos.
pip install agentboxx
Or install from source:
git clone https://github.com/Agentboxx-dev/Agentboxx.git
cd Agentboxx
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
Try it with one command (no Docker, no API key, nothing left behind):
agentbox demo
Run the demos from the repo:
python examples/demo_agent.py # stuck-agent demo (local backend)
python examples/demo_docker.py # shows what the Docker sandbox blocks
python examples/demo_agent_loop.py # full pipeline: detect, hint, recover
agentbox keygen # generate Ed25519 keypair (~/.agentbox/ed25519.pub)
agentbox report runs/agent-demo.ndjson # readable summary
agentbox verify runs/agent-demo.ndjson # symmetric integrity check
agentbox verify runs/agent-demo.ndjson --pubkey ~/.agentbox/ed25519.pub # public-key receipt check
agentbox bundle runs/agent-demo.ndjson -o demo.agentbox.zip # package self-contained offline evidence bundle
agentbox verify demo.agentbox.zip # verify directly from offline archive
agentbox replay runs/agent-demo.ndjson # step through a session in an interactive terminal player
agentbox --version
report uses color for errors and warnings when writing to a terminal. Set NO_COLOR=1 to turn it off. It supports --format text|json|html (default: text) and --output <file> (or -o) to export reports; HTML reports are completely self-contained with no external assets.
Example: a stuck agent recovers
The scripted agent repeats a failing command. After the third identical failure on an unchanged workspace, the detector raises warnings and the next observation carries a hint:
[2] Run it.
$ python3 main.py -> exit 1
[3] Run it.
$ python3 main.py -> exit 1
[4] Run it.
$ python3 main.py -> exit 1
!! warn: loop.exact
!! warn: loop.error_repeat
!! warn: loop.no_progress
[5] The hint is right: x = 0 causes the crash. Fix the value.
$ sed -i 's/x = 0/x = 2/' main.py -> exit 0
[6] Run it again.
$ python3 main.py -> exit 0
Result: {'reason': 'final_answer', 'final': 'Fixed the divide-by-zero; script prints 5.0.'}
Example: tamper detection
Change any value in a log file and verification fails:
$ agentbox verify runs/demo.ndjson
LOG HAS BEEN TAMPERED WITH OR IS CORRUPT:
- line 3: content was modified
Use it in your own agent
from agentbox import Recorder
from agentbox.docker_backend import DockerSandbox
sandbox = DockerSandbox("./workspace") # no network by default
sandbox.start()
rec = Recorder("my-session", workspace="./workspace", sandbox=sandbox)
result = rec.run("pytest -x", thought="Run the tests")
print(result["signals"]) # loop warnings, if any
rec.close("done") # also stops the container
agentbox.agent.run_agent wraps this in a ReAct-style loop. ScriptedModel needs no API key. GeminiModel connects to Google Gemini via standard-library REST (needs GEMINI_API_KEY, validated end-to-end). AnthropicModel is an optional adapter (pip install anthropic, set ANTHROPIC_API_KEY).
Record tool calls (MCP and other agent frameworks)
Agents built on the Model Context Protocol, the OpenAI Agents SDK or LangChain act through tool calls, not shell commands. Record each one with record_tool_call:
rec.record_tool_call(
tool_name="search_issues",
tool_source="mcp:github", # free text: mcp:<server>, builtin, langchain, function...
arguments={"query": "is:open label:bug"},
result={"total": 3},
duration_ms=412,
is_error=False,
)
A tool call is a step: it shares step_index with commands, counts toward a contract's max_steps, and feeds the loop detectors. Secrets in arguments and result are removed before anything is signed (including values under keys such as password or api_key). Anything larger than 64 KB is cut to its head and tail, with its size and a SHA-256 of the whole redacted value kept. Tool calls appear in agentbox report (text, JSON and HTML), in agentbox replay, and agentbox verify prints how many a verified log holds. Details: docs/log-format.md.
LangChain & LangGraph integration
Agentboxx records LangChain tool executions into its cryptographic flight recorder:
pip install "agentboxx[langchain]"
Use AgentboxxCallbackHandler directly with tools, agents, or chains:
from agentbox.integrations.langchain import AgentboxxCallbackHandler
from langchain_core.tools import tool
@tool
def calculate(expression: str) -> str:
"""Evaluate a math expression."""
return str(eval(expression))
handler = AgentboxxCallbackHandler("session-langchain")
calculate.invoke({"expression": "10 * 4.2"}, config={"callbacks": [handler]})
handler.close("finished")
Run agentbox verify runs/session-langchain.ndjson to verify the log's cryptographic integrity.
Task contracts & host-side assertions
Instead of trusting an agent's self-reported claim that a task succeeded, attach a TaskContract to enforce execution boundaries (maximum steps, cumulative duration, deadline) and execute objective host-side success assertions:
from agentbox import (
Recorder,
TaskContract,
assert_file_exists,
assert_file_contains,
assert_command,
)
contract = TaskContract(
task_id="solve-issue-42",
max_steps=15,
deadline_s=120.0,
assertions=[
assert_file_exists("dist/bundle.js"),
assert_file_contains("package.json", r'"version":\s*"1\.0\.0"'),
assert_command("pytest tests/test_solution.py"),
],
)
rec = Recorder("eval-session", workspace="./workspace", contract=contract)
# Run agent actions...
rec.close("finished")
The evaluation verdict (contract.verdict) is HMAC-signed and hash-chained into the flight log, and surfaced in agentbox report (text, JSON, and HTML).
What agentbox verify reports
| Result | Exit code | Meaning |
|---|---|---|
OK |
0 | Chain, signatures and the closing manifest all match |
TAMPERED |
1 | A record was edited, removed or reordered, or the log no longer matches its signed manifest |
INCOMPLETE |
2 | The log is intact so far but was never closed: a crash, a running session, or a removed tail |
| (error) | 3 | The file is missing, empty, a directory or unreadable. This is not a verdict on the log, and report uses the same code |
The manifest (<session>.manifest.json) is written when a session closes and records the final record count and hash, signed with the same key. The verifier requires the manifest: a closed session whose manifest is missing is reported as INCOMPLETE, and a truncated log whose manifest is still present is reported as TAMPERED. Anyone holding the symmetric signing key can verify HMAC signatures. For third-party and customer verification, Agentbox generates an asymmetric Ed25519 run receipt (<session>.receipt.json) on close. Auditors holding only the public key can verify that the run was executed and finalized by the keyholder without holding the private signing secret.
Replay a session in the terminal
agentbox replay <log> is an interactive player: step through a run one frame at a time and see the thought, command, exit code, output, detector signals and sandbox resources for each step, with the verification result on screen. It is for debugging an agent that looped, hallucinated or crashed, and for auditors reading a run.
pip install "agentboxx[ui]" # the player uses the optional rich package
agentbox replay runs/agent-demo.ndjson
| Key | Action |
|---|---|
→, Space, n |
next step |
←, p |
previous step |
Home / End |
first / last step |
a |
toggle autoplay |
v |
verify the log again |
q, Esc |
quit |
The header shows a dot per step (failed steps in red) and a badge: VERIFIED ✓, TAMPERED ✗ or INCOMPLETE ⚠. Tampered and unclosed logs can still be replayed; the problem is shown in a banner. The exit code mirrors agentbox verify (0, 1, 2; 3 for a missing or unreadable file), so agentbox replay --plain works in scripts. Without a terminal, or with --plain, it prints one frame as plain text and needs no extra package. See docs/cli.md for all options.
Detection signals
| Signal | Meaning |
|---|---|
loop.exact |
The same command was repeated on an unchanged workspace |
loop.error_repeat |
The same normalized error keeps recurring |
loop.no_progress |
Several steps failed while no files changed |
loop.cycle |
The agent alternates between the same few commands |
Warnings become hints for the model. Critical severity (for example five identical repeats) stops the run.
Sandbox resource and crash events
With the Docker backend, the host records two extra signed events after each step: sandbox.resource (memory, CPU, process count) and sandbox.crash (an out-of-memory kill, or a container that stopped). Everything is read on the host through Docker, so the agent cannot influence it.
- Resource sampling adds about a second per step. Turn it off with
DockerSandbox(resource_stats=False). - A sample is a snapshot after the step, not a peak.
- The local backend has no equivalent, and
agentbox reportdoes not show these events yet.
Error signatures
Repeated-error detection compares normalized error signatures, so the same failure matches even when line numbers, file paths or runtime versions differ.
| Language | Recognized output | Signature class |
|---|---|---|
| Python | Tracebacks | Exception name, e.g. ZeroDivisionError |
| Node.js | Uncaught errors with stack frames | e.g. TypeError, Error[ERR_MODULE_NOT_FOUND] |
| Go | Panics, fatal errors, compile errors | GoPanic, GoFatalError, GoCompileError |
| Rust | Panics, compile errors | RustPanic, RustCompileError[E0308] |
| Java | Exceptions, caused-by chains, compile errors | Exception class (e.g. java.lang.NullPointerException), JavaCompileError[cannot find symbol] |
| Ruby | Runtime errors, quote styles | Exception name, e.g. ZeroDivisionError |
Anything else falls back to hashing the last lines of stderr. To add a language, see src/agentbox/error_signatures.py.
Secret redaction
Commands, output and the model's reasoning are redacted before they are signed, because a signed record cannot be edited afterward. Recognized: private key blocks, AWS, GitHub, Slack and Google keys, sk- style API keys, JWTs, Authorization headers, passwords in URLs, and NAME=value where the name contains password, secret, token or api_key. Each step records only a count per pattern, never the value.
Limits to know about:
- Patterns are heuristics. They miss some secrets (for example a secret with no recognizable name or format) and sometimes hide harmless values such as a long
*_token=setting. - The command itself still runs with the real value. Only the record is redacted.
- With the agent loop, the model also receives the redacted output, so it cannot read a secret that a command printed.
- Files in the workspace are not logged, but anything a command prints from them is covered by these patterns only.
- Add your own patterns with
agentbox.redact.add_pattern(name, regex).
Log format
The log format is documented in docs/log-format.md and described by JSON Schemas (record, manifest). examples/verify_standalone.py verifies a log using only the Python standard library, as an independent check that the spec is complete.
Threat model
- Docker backend (Recommended & Primary Boundary): Commands run as a non-root user in a container with disabled network (or explicit domain allowlisting via
EgressPolicy), a read-only root filesystem, all Linux capabilities dropped (--cap-drop ALL),no-new-privileges:true, and strict CPU, memory and process limits. The signing key and logs remain strictly on the host and are never mounted into the container. Contract assertion commands (assert_command) execute in fresh, ephemeral containers with workspace mounted read-only (:ro). - Local backend (Dev-Only / Untrusted-Unsupported): The local backend provides no isolation boundary. Commands execute with your host user privileges and could access host files or the signing key. It is strictly intended for local development, unit tests, and trusted experiments. Untrusted workloads are explicitly unsupported on the local backend. As a defense-in-depth safeguard, contract
assert_commandexecution is refused on the local backend unlessallow_unsafe_host_exec=Trueis explicitly specified (which emits a high-severity security warning). - File & Contract Assertions: Host-side file assertions use
_safe_resolve(),_safe_read(), and_safe_lstat()to reject symlinks, FIFOs, device nodes, and path traversal escaping the workspace. Test suite files are integrity-hashed prior to agent execution to detect and record any tampering. - Defense in depth: Docker isolation is strong but not an absolute hypervisor boundary. In production or multi-tenant environments, run Docker inside disposable virtual machines.
- Log integrity: Hash-chained records and Ed25519 run receipts prove that records were not altered, reordered, or forged after execution; they do not prove model intent and cannot capture operations that bypass the registered execution harness.
Limitations
- Windows is supported and tested in CI (Python 3.11–3.13 on
windows-latest). Process-tree termination usestaskkill /F /Tto kill runaway commands and all their children. The Docker backend runs as user1000:1000in the container (override withDockerSandbox(user=...)); Docker Desktop with Linux containers is required. The local backend automatically discovers Git Bash (in Program Files, LocalAppData, or on PATH), usingpythoninstead of Unixpython3. - Detector thresholds are initial values, not calibrated on real agent traces.
- Network egress: outbound connections are filtered by domain and recorded as signed audit events; full HTTP/HTTPS request and response payload capture is not recorded.
- No semantic drift detection yet; detection is command and state based.
- Error signatures cover Python, Node.js, Go, Rust, Java and Ruby. Other languages use a generic fallback.
Roadmap
- Signed, hash-chained event log with verification
- Docker sandbox backend
- Loop detection with hint feedback
- ReAct-style agent loop
- Stable error signatures for Python, Node.js, Go, Rust, Java and Ruby
- Truncation detection with a signed closing manifest
- Secret redaction before signing
- Output size cap and process-tree kill on timeout (#22)
- Sandbox resource and crash events (Docker backend)
- Public-key signing so third parties can verify logs (#23)
- Validate against a live model (#5)
- Network egress filtering proxy & connection audit events (#24)
- Session replay UI (#29)
- First-class MCP tool-call recording (#50)
- Semantic drift detector
- Threshold calibration on recorded sessions
Live Model Execution & Task Contracts
You can connect real LLMs (Gemini, Claude, etc.) directly to Agentboxx with host-side task contracts:
import os
from agentbox import (
Recorder,
TaskContract,
assert_file_exists,
assert_file_contains,
)
from agentbox.agent import GeminiModel, run_agent
# 1. Define a verifiable Task Contract
contract = TaskContract(
task_id="prime-calculation",
description="Calculate prime sum and write to file",
max_steps=10,
max_duration_s=60.0,
assertions=[
assert_file_exists("prime_sum.py"),
assert_file_exists("result.txt"),
assert_file_contains("result.txt", "1060"),
],
)
# 2. Set up Recorder
rec = Recorder(
session_id="my-run",
workspace="./workspace",
contract=contract,
)
# 3. Run with live Gemini model (requires GEMINI_API_KEY)
model = GeminiModel(model="gemini-2.5-flash")
goal = "Write prime_sum.py to sum primes under 100, save to result.txt, and run it."
try:
result = run_agent(goal, model, rec)
finally:
rec.close("Finished")
Inspect and Verify the Run
# View terminal summary with Task Contract verdict
agentbox report ./runs/my-run.ndjson
# Generate interactive HTML dashboard
agentbox report ./runs/my-run.ndjson --format html -o report.html
# Cryptographically verify the tamper-evident hash chain
agentbox verify ./runs/my-run.ndjson
# Verify using a custom key file (if key_path was customized)
agentbox verify ./runs/my-run.ndjson -k ./runs/key
Contributing
Contributions are welcome. Start with CONTRIBUTING.md and the issues labeled good first issue.
License
Apache-2.0. See LICENSE.
Metadata
Release files for agentboxx 0.3.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agentboxx-0.3.1.tar.gz | 120.2 kB | With provenance | Details for agentboxx-0.3.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentboxx-0.3.1-py3-none-any.whl | Python 3 | none | any | Details for agentboxx-0.3.1-py3-none-any.whl |
Total release size: 196.6 kB
Release files / agentboxx-0.3.1.tar.gz
| Download URL | agentboxx-0.3.1.tar.gz |
|---|---|
| Size | 120.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
108c583615be508f5944dec66397079ac03224424e668687cbe32bf6a7ffae8d
|
|
BLAKE2b-256 checksum How to use checksums |
62e942ac239550e0e837fdbb5ec7b7a666f00ab67dcd39d32775e09f01c710c4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logRelease files / agentboxx-0.3.1-py3-none-any.whl
| Download URL | agentboxx-0.3.1-py3-none-any.whl |
|---|---|
| Size | 76.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c649c02e1932680d4f655fcc08d576e25c37f2babbc5c31d0e59707ddb3a47ef
|
|
BLAKE2b-256 checksum How to use checksums |
04d27cfaa612ab41c309f039798777991272b314fc9378c9d9fb4199ab939610
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logSecurity for agentboxx 0.3.1
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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for agentboxx-0.3.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logA 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.