Skip to main content

agentbox

A tamper-evident flight recorder for AI agents.

Run agent commands in an isolated sandbox, record what actually happened, sign every record, and catch agents that get stuck.

CI License Python Status


Why agentbox

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, HMAC-signed event log and verify_file
executor.py Local command runner, error fingerprints, workspace hashing
docker_backend.py Runs commands in a locked-down container
loop_detector.py Exact repeat, repeated error, no-progress and cycle detection
recorder.py Main API: Recorder.run(command)
agent.py Minimal ReAct-style loop that feeds detector hints back to the model

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/Prathmesh010190/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 report runs/agent-demo.ndjson   # readable summary
agentbox verify runs/agent-demo.ndjson   # integrity check
agentbox list                            # every log in ./runs: session, start time, steps, verifies?
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).

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 who can read the signing key can forge both files, so copy manifests somewhere the agent host cannot write to if that matters. Public-key signing, as used for Nanda Town's evidence attestations, would let third parties verify logs without holding a secret, and is a possible future change.

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

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: commands run as a non-root user in a container with no network, a read-only root filesystem, all Linux capabilities dropped, no-new-privileges, and CPU, memory and process limits. The signing key and logs stay on the host and are never mounted into the container.
  • Local backend: no isolation. The agent runs as your user and could read the signing key. Use it only for trusted experiments.
  • Docker isolation is strong but not a perfect boundary. Run untrusted agents in a disposable VM.
  • The log shows that records were not altered after writing. It does not prove the agent's intent, and it cannot see anything that bypasses the executor.

Limitations

  • Windows is experimental. The Docker backend no longer needs Unix user IDs and runs as user 1000:1000 in the container (override with DockerSandbox(user=...)), but it has not been run on real Windows hardware yet. It needs Docker Desktop with Linux containers. The local backend still needs bash (Git Bash), and on Windows a timeout kills only the direct child process.
  • Detector thresholds are initial values, not calibrated on real agent traces.
  • No network capture yet (the sandbox simply has no network).
  • No semantic drift detection yet; detection is command and state based.
  • Error signatures cover Python, Node.js and Go only. 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 and Go
  • Truncation detection with a signed closing manifest
  • Secret redaction before signing
  • Output size cap and process-tree kill on timeout
  • Sandbox resource and crash events (Docker backend)
  • Public-key signing so third parties can verify logs
  • Validate against a live model (#5)
  • Network egress capture (design in docs/network-egress.md)
  • Semantic drift detector
  • Session replay UI
  • Threshold calibration on recorded sessions

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.2.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.2.1
File Size Uploaded Provenance Actions
agentboxx-0.2.1.tar.gz 52.9 kB With provenance Details for agentboxx-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agentboxx 0.2.1
File Interpreter ABI Platform Actions
agentboxx-0.2.1-py3-none-any.whl Python 3 none any Details for agentboxx-0.2.1-py3-none-any.whl

Total release size: 89.5 kB

Release files / agentboxx-0.2.1.tar.gz

Download URL agentboxx-0.2.1.tar.gz
Size 52.9 kB
Tags Source
SHA-256 checksum
How to use checksums
5132bb808fda359cb6a9173f7b92bf29a70b79eb030de312237ca172a01a4b3b
BLAKE2b-256 checksum
How to use checksums
22ed36f231e8cb06ad8246fc00d1da59c44ec8450d2c37f71cd6b947b71291f9
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 1, 2026.

Transparency log

Release files / agentboxx-0.2.1-py3-none-any.whl

Download URL agentboxx-0.2.1-py3-none-any.whl
Size 36.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ed2ac34f799f3df9469f0a1eae24641a9a3f43bd8e173f2949600d329b6eced6
BLAKE2b-256 checksum
How to use checksums
3376a2d967b9184dc76ee12324e185c7a4d999591f595f15b71825366c0693c5
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 1, 2026.

Transparency log

Security for agentboxx 0.2.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.2.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 1, 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