Skip to main content

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

agentbox architecture: model, Docker sandbox, recorder, signed log, and loop detector feeding hints back to the model

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 report does 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_command execution is refused on the local backend unless allow_unsafe_host_exec=True is 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 uses taskkill /F /T to kill runaway commands and all their children. The Docker backend runs as user 1000:1000 in the container (override with DockerSandbox(user=...)); Docker Desktop with Linux containers is required. The local backend automatically discovers Git Bash (in Program Files, LocalAppData, or on PATH), using python instead of Unix python3.
  • 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)

Source distribution for agentboxx 0.3.1
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)

Table of built distributions (wheels) for agentboxx 0.3.1
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

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.

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