# safeagents

> A lightweight local proxy that checks an agent's model tool calls and blocks unsafe ones before the coding harness runs them.

safeagents is an open-source local proxy from Hugging Face that sits between an agent harness and its model server. It inspects every tool call the model makes before the harness sees it, and replaces blocked calls with a text notice so nothing is executed. It works with any harness that lets you set a base URL, over OpenAI Chat Completions or Anthropic Messages, streaming or not.

## What It Is

safeagents is a command-line security layer for coding agents. You start a proxy pointed at the model server your agent normally uses, then set the agent's base URL to the proxy address (default 127.0.0.1:8787). The README names Claude Code, Pi, Hermes and OpenCode as examples, and says setup guides for 12 coding agents are in its docs folder.

## How the checks work

Each tool call passes through up to three stages:

- Request-only checks block calls that use a tool the request never declared, or whose arguments contain a host (URL or bare IP) that appears nowhere in the conversation.
- atif-scan checks convert the conversation into an ATIF trace and run detectors on the pending call, such as reading /proc/1/environ, curl --noproxy, Kubernetes service-account token access, and unshare/nsenter. Findings at or above the configured severity are blocked; milder ones mark the call suspicious.
- An optional decision model (judge) reviews suspicious calls and answers allow or block. It sees only the user's text, the tool call and the findings, can add blocks but never lift one, and clean calls never reach it.

Streaming adds no latency: each tool call is held until its arguments are complete, then released unchanged or replaced, while text is forwarded as it arrives.

## Monitoring and review

Running in the foreground shows a live terminal view with a histogram of PASS, WARN, FLAG and BLOCK verdicts and the latest calls. A log-only mode reports what would be blocked without changing responses. Blocked, flagged and suspicious calls are saved to a local journal readable only by the user, and the inspect command lists them or shows one call in full, including the task, finding and arguments.

## Setup path

Install scripts for macOS, Linux/WSL and Windows PowerShell install uv if needed and set up safeagents as a uv tool. Commands include start, ls, stop and inspect, with options for extra allowed hosts, severity thresholds, judge URL and model, and fail-closed judging. A built-in allowlist covers loopback, GitHub, PyPI, Hugging Face, npm and crates.io. It is released under Apache 2.0.

## Features
- Local proxy between agent harness and model server
- Blocks tool calls that use undeclared tools
- Blocks calls with hosts not present in the conversation
- atif-scan detectors for risky commands
- Optional judge model for suspicious calls
- Log-only mode
- Configurable block severity and host allowlist
- Streaming support without added latency
- Live terminal view of call verdicts
- Local journal and inspect command for flagged calls
- Supports OpenAI Chat Completions and Anthropic Messages

## Integrations
Claude Code, Pi, Hermes, OpenCode, OpenAI Chat Completions, Anthropic Messages, atif-scan, uv

## Platforms
WINDOWS, MACOS, LINUX, API, CLI

## Pricing
Open Source

## Links
- Website: https://github.com/huggingface/safeagents
- Documentation: https://github.com/huggingface/safeagents/blob/main/docs/README.md
- Repository: https://github.com/huggingface/safeagents
- EveryDev.ai: https://www.everydev.ai/tools/safeagents