handcuff 1.3.0

Handcuff is a security-first observability tool for AI agents, featuring tamper-evident OS-level recording, prompt-injection circuit breakers, and Docker sandboxing.

Handcuff: Dashcam and Sandbox for AI Agents

Handcuff is a security-first observability and sandboxing tool designed specifically for AI agents. It acts as a local, tamper-evident dashcam that records the operating system-level side effects of your AI agents—such as spawned processes, written files, and open network connections.

In addition to monitoring, Handcuff provides a Docker Sandbox (no network, dropped capabilities, and resource ceilings by default; networking is opt-in for download workloads) and a Prompt-Injection Circuit Breaker to execute unverified AI-generated code or untrusted file downloads in isolation, shielding the host system from malicious actions and data breaches.

Note: For full implementation details, architectural diagrams, and TUI screenshots, please refer to the Handcuff GitHub Repository.

Key Features

• Tamper-Evident Timeline: Every system event is SHA-256 hash-chained, and session heads are Ed25519-signed. You can use the handcuff verify command to cryptographically re-validate the chain of events from the database or exported JSON reports. Verification pins the signature against this machine's key (or a --pubkey you supply for exports from other machines); record your key's fingerprint out-of-band with handcuff key fingerprint.
• Docker-Isolated Sandboxing: The DockerSandbox and langchain_sandbox integrations execute risky agent actions—such as downloading external code or cloning repositories—inside ephemeral, memory-limited Docker containers.
• Prompt-Injection Circuit Breaker: Handcuff employs heuristic scanning (handcuff.rules.injection) on files transferred out of the sandbox. It detects instruction overrides, fake system turns, data-exfiltration commands, and obfuscated payloads (e.g., hidden Unicode, suspicious base64 blobs). A positive match blocks further network egress for the agent.
• Framework Integration: Built-in support for LangChain and LangGraph via the HandcuffHandler. Handcuff integrates seamlessly as a BaseCallbackHandler, isolating parallel runs correctly through native run_id state management.
• Live Observability: The handcuff tui command opens a real-time, terminal-based dashboard displaying trust meters, flagged event cards, and live monitoring across all active agent sessions.
• Local-Only Guarantee: The core system is completely disconnected from external cloud services. Captured content is strictly treated as data and never interpreted as instructions, eliminating recursive agent-hijacking vectors.

Installation

Handcuff requires Python 3.11 or newer. To install the package from PyPI:

# Standard installation
pip install handcuff

# Installation with LangChain integration and Docker Sandboxing support
pip install "handcuff[langchain,sandbox]"

Quickstart

You can use Handcuff from the command line to monitor an agent script, view active sessions, and verify audit logs.

# Record an agent (or any arbitrary command) and log all OS events
handcuff watch -- python my_agent.py

# Launch an MCP Proxy to intercept and secure tool calls between agents and servers
# Use `--llm-guard` to block malicious tool calls using a local Ollama model (100% private)
handcuff mcp --llm-guard npx -y @modelcontextprotocol/server-filesystem /tmp

# View the live TUI dashboard in a separate terminal
handcuff tui

# List all recorded sessions
handcuff sessions

# Replay a specific past session
handcuff replay <SESSION_ID>

# Export a tamper-evident HTML report
handcuff export <SESSION_ID> --format html

# Cryptographically verify the session's hash chain
handcuff verify <SESSION_ID>

Using the LangChain Integration

Add the HandcuffHandler to any LangChain or LangGraph invocation to start recording agent telemetry automatically:

from handcuff.integrations.langchain import HandcuffHandler

handler = HandcuffHandler()
result = my_agent.invoke(inputs, config={"callbacks": [handler]})
handler.close()

Using the Docker Sandbox

For safe, isolated tool execution, use the provided DockerSandbox:

from handcuff.sandbox.manager import DockerSandbox

# Launch a secure container with strict memory limits and a 30-second execution timeout
with DockerSandbox() as sandbox:
    # Execute commands in the container
    sandbox.execute("echo 'Untrusted data processing'")
    
    # Safely transfer files back to the host, triggering the injection scanner
    sandbox.copy_quarantined(
        container_path="/sandbox/output.txt",
        host_path="./host_workspace/output.txt"
    )

Contributing and Internal Documentation

If you are a developer and want to contribute to Handcuff, refer to the existing codebase and CONTRIBUTING.md for more information. The codebase is well-documented, following a modular architecture that separates concerns between monitoring, sandboxing, and the TUI.

Note: Handcuff currently prioritizes the Windows ecosystem (psutil, watchdog, Windows ACL/Firewall) and PyInstaller for distributions. While macOS and Linux are partially supported by the underlying abstraction layers, active enforcement rules are optimized for Windows environments.