shepherd-agents/shepherd

What it solves

Shepherd provides a secure, supervised environment for AI agents to perform work. It solves the problem of "blind trust" in agents by ensuring that no agent-generated changes are applied to a user's filesystem until they are explicitly reviewed and accepted. It also provides a way to to record and reverse agent actions through durable execution traces.

How it works

Shepherd acts as a runtime substrate that records agent runs as inspectable traces. It uses a "proposal" system where agent outputs are held as retained outputs in a separate area rather than being written directly to the workspace. Users can then select, apply, or discard these proposals.

To ensure security, Shepherd uses OS-level grant enforcement (macOS Seatbelt and Linux Landlock) to restrict agent permissions. Permissions are defined directly in the Python function signature of the task; for example, specifying ReadOnly or ReadWrite for a repository handle determines what the agent can actually do at the native syscall level.

Who it’s for

It is designed for developers and researchers building AI agents that need to interact with local files and repositories while maintaining strict supervision and safety guarantees.

Highlights

• Reversible Execution Traces: Records agent runs as durable, inspectable records.
• OS-Level Sandboxing: Enforces permissions via macOS Seatbelt and Linux Landlock to prevent unauthorized filesystem access.
• Reviewable Proposals: Agent outputs are held as "retained outputs" that must be manually accepted before being merged into the workspace.
• Permission-as-Signature: Uses Python type hints in function signatures to define the agent's permission surface.