handcuff 1.7.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), a Hybrid Prompt-Injection Circuit Breaker, and an MCP Proxy Firewall 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. Use the handcuff verify command to cryptographically re-validate the chain of events from the database or exported JSON/HTML 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.
• Hybrid Prompt-Injection Circuit Breaker: Handcuff employs a true hybrid pipeline. Incoming untrusted content is first evaluated using deterministic, zero-latency regex signatures. If this rapid heuristic check is passed, Handcuff optionally falls back to a deep semantic evaluation using a local Ollama model to accurately catch novel adversarial injections and malicious payloads.
• MCP Proxy Firewall: Secure communication between agents and external Model Context Protocol (MCP) servers using handcuff mcp. Intercepts and scans tool calls using the local LLM Guard before they reach the server.
• 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.

Installation

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

# Standard installation
pip install handcuff

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

Complete User Guide

Handcuff can be used as a CLI tool to monitor processes, a proxy firewall for MCP servers, or a Python library integrated directly into your LangChain/LangGraph applications.

1. The Handcuff CLI

The handcuff command line tool provides a suite of features for recording and analyzing agent sessions.

• handcuff watch -- <command> Record an agent (or any arbitrary command) and log all OS-level events. This acts as the dashcam, recording files modified, processes spawned, and network connections opened. Example: handcuff watch -- python my_agent.py

• handcuff mcp [--llm-guard] <command> Launch an MCP Proxy to intercept and secure tool calls between agents and servers. The --llm-guard flag enables semantic scanning using a local Ollama model to block malicious tool calls with 100% privacy. Example: handcuff mcp --llm-guard npx -y @modelcontextprotocol/server-filesystem /tmp

• handcuff tui Open the real-time Textual UI dashboard in a separate terminal. It connects to the SQLite database and displays live events, risk meters, and critical alerts (like Quarantine violations).

• handcuff sessions List all recorded sessions in the local database.

• handcuff replay <SESSION_ID> Replay a specific past session in the terminal to see what happened step-by-step.

• handcuff export <SESSION_ID> --format <html|json> Export a tamper-evident report of a session to share with security teams or auditors.

• handcuff verify <SESSION_ID> Cryptographically verify the session's hash chain to ensure no logs were tampered with or deleted.

2. Python Integration (LangChain/LangGraph)

You can embed Handcuff directly into your agent's code using the HandcuffHandler. This integrates seamlessly as a BaseCallbackHandler, isolating parallel runs correctly through native run_id state management.

Where to make changes: Simply add the handler to the callbacks list when invoking your agent or initializing your LLM.

from handcuff.integrations.langchain import HandcuffHandler

handler = HandcuffHandler()

# Example with LangGraph or AgentExecutor
result = my_agent.invoke(
    {"input": "Do some research"}, 
    config={"callbacks": [handler]}
)
handler.close()

3. Using the Docker Sandbox

For safe, isolated tool execution, Handcuff provides the DockerSandbox and langchain_sandbox wrappers. These ensure that tools dealing with untrusted data (like web scrapers or code executors) run inside a secure container.

Where to make changes: Wrap your standard LangChain tools using langchain_sandbox or use DockerSandbox manually in your custom tool definitions.

from handcuff.sandbox.manager import DockerSandbox

# Hardened defaults: no network, read-only root fs, capability drop,
# memory/pids/CPU ceilings. Pass allow_network=True only for workloads
# that must reach the internet (e.g. downloading a dataset).
with DockerSandbox(allow_network=True) as sandbox:
    # Execute commands in the container
    sandbox.execute("curl -sO https://example.com/untrusted_data.csv")
    
    # Safely transfer files back to the host. 
    # This automatically triggers the Prompt-Injection Circuit Breaker (Hybrid Scanner).
    # If the file contains malicious instructions, it will raise a QuarantineViolation 
    # and DESTROY the file before it reaches your host system.
    sandbox.copy_quarantined(
        container_path="/sandbox/untrusted_data.csv",
        host_path="./host_workspace/clean_data.csv"
    )

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.