shepherd-agents/shepherd

What it solves

Shepherd provides a runtime substrate for AI agents that requires high levels of inspection, reversibility, and supervision. It solves the problem of agents making uncontrolled changes to a filesystem, allowing users to review and approve proposed changes before they are actually applied to the workspace.

How it works

Shepherd records agent activities as durable, inspectable execution traces. When an agent performs a task, its outputs are held as "retained outputs" (proposals) rather than being written directly to the user's files. Users can then inspect these changesets and choose to select, apply, release, or discard them.

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

Who it’s for

It is designed for developers building agentic workflows who need a safety layer to prevent agents from accidentally corrupting data or making unauthorized changes, as well as researchers working on programmable meta-agents.

Highlights

• Reversible Execution: Agent runs are recorded as traces, allowing outputs to be reviewed and discarded or merged via three-way merges.
• OS-Level Sandboxing: Enforces permissions (read-only vs read-write) at the native syscall jail on macOS and Linux.
• Signature-Based Permissions: Permissions are declared explicitly in the Python task signature, making the security surface easy to audit.
• Durable Traces: Maintains a machine-readable record of runs that can be inspected via a CLI.