handcuff 0.3.1

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 robust Docker Sandbox and Prompt-Injection Circuit Breaker to safely execute unverified AI-generated code or untrusted file downloads in complete isolation, shielding the host system from malicious actions and data breaches.

Core Architecture

Handcuff operates with a zero-trust, local-only architecture. All data remains on the host machine unless an external webhook is explicitly configured. Below is an architectural overview of how Handcuff processes, monitors, and quarantines AI agent activities.

flowchart TD
    A[AI Agent Framework\nLangChain / LangGraph] -->|Tool Invocation| B(Handcuff Gateway)
    B --> C{Is Action Safe?}
    
    C -->|Yes| D[Standard OS Execution]
    C -->|Unknown / Risky| E[Docker Sandbox & Quarantine]
    
    E --> F[Execute in Isolated Container]
    F --> G[Extract Files to 100MB Memory Buffer]
    G --> H[Heuristic Prompt-Injection Scanner]
    
    H -->|Clean| I[Persist to Host Workspace]
    H -->|Malicious| J[Block & Alert]
    
    D --> K[(Tamper-Evident SQLite DB)]
    I --> K
    J --> K
    
    K --> L[Textual TUI Dashboard\nLive Monitoring & Alerts]

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

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