Why wsh?

AI agents run commands as your Unix user. They have the same permissions as you. Today, the options for restricting them are either nothing — or a week of sysadmin work that still leaves gaps. wsh fills that gap.

This page makes the case in three parts:

1. The complexity of doing it yourself
2. What you simply can’t do with standard tools
3. The macOS problem

1. Side by side: standard tools vs wsh

Let’s say you want to let a coding agent run git, cargo, and rustc in a project directory, deny everything else, and log what it does. Here’s what that looks like with standard Linux tools:

Without wsh (~30 minutes, Linux only)

# 1. Create a restricted user for the agent
sudo useradd -m -s /bin/rbash agent-codex
sudo mkdir -p /home/agent-codex/bin

# 2. Symlink only the allowed binaries
sudo ln -s /usr/bin/git /home/agent-codex/bin/git
sudo ln -s /usr/bin/cargo /home/agent-codex/bin/cargo
sudo ln -s /usr/bin/rustc /home/agent-codex/bin/rustc
sudo ln -s /usr/bin/cat /home/agent-codex/bin/cat
sudo ln -s /usr/bin/ls /home/agent-codex/bin/ls
sudo ln -s /usr/bin/mkdir /home/agent-codex/bin/mkdir
# ... repeat for every coreutils command the agent needs

# 3. Lock down PATH so only symlinked binaries are available
echo 'export PATH="$HOME/bin"' | sudo tee /home/agent-codex/.bashrc
sudo chattr +i /home/agent-codex/.bashrc

# 4. Write an AppArmor profile
sudo tee /etc/apparmor.d/agent-codex << 'EOF'
#include <tunables/global>
profile agent-codex /home/agent-codex/** {
  #include <abstractions/base>
  /usr/bin/git rix,
  /usr/bin/cargo rix,
  /usr/bin/rustc rix,
  /home/agent-codex/** rw,
  deny /etc/shadow r,
  deny /home/pete/** rw,
  # ... 50+ more deny rules for every sensitive path
}
EOF
sudo apparmor_parser -r /etc/apparmor.d/agent-codex

# 5. Set up audit logging
sudo auditctl -a always,exit -F uid=$(id -u agent-codex) -S execve
sudo mkdir -p /var/log/agent-audit
# Now write a custom log parser...
# And a log rotation config...
# And figure out how to make the output readable...

# 6. Run the agent as the restricted user
sudo -u agent-codex -i codex --workdir /home/agent-codex/project

# 7. Review what happened (good luck)
sudo ausearch -ua $(id -u agent-codex) | aureport -x

That’s a restricted shell, manual symlinks, a MAC profile, kernel audit rules, and a custom log pipeline. Every time you add a new tool, you touch four different configs. And the audit output is essentially raw syscall data.

With wsh (~2 minutes, Linux and macOS)

# 1. Install
curl -fsSL https://warrant.sh/install.sh | sudo sh

# 2. Set up policy for your agent
wsh setup codex

# 3. Review what happened
wsh audit

Two commands. Policy enforcement, tamper-proof audit logging, shell integration, and human-readable output. Works on both Linux and macOS.

Maintenance comparison

2. What you can’t do at all with standard tools

The comparison above is generous. It assumes standard tools can approximate what wsh does. In reality, there’s an entire class of policy that no combination of standard Unix tools can express.

The reason is architectural: tools like AppArmor, SELinux, and auditd operate at the kernel level. They see binaries, file paths, and network sockets. They have no visibility into what a command means — its arguments, its intent, its application-layer semantics.

Semantic policies: impossible without wsh

The fundamental distinction: AppArmor controls what programs can run. wsh controls what programs can do.

This isn’t a criticism of AppArmor or SELinux — they’re excellent at what they do. But they were designed for a world where programs are trusted and the concern is privilege escalation between users. AI agents are a fundamentally different threat: a program running as you, with your permissions, that needs to be constrained at the semantic level.

3. The macOS problem

Everything above assumed Linux. On macOS — where a large proportion of developers (and AI agents) actually run — the situation is worse.

macOS simply does not provide the primitives needed to restrict AI agents at the OS level. You can’t write an AppArmor profile because AppArmor doesn’t exist. You can’t use sandbox-exec because Apple deprecated it. You can’t filter network per-process because pf doesn’t support it.

wsh works identically on both platforms. Same policies, same manifests, same audit system. Install once, enforce everywhere.

The bottom line

There are three levels of AI agent security today:

1. Nothing — the agent runs as you with full access. This is the default for every major AI coding agent.
2. DIY with OS tools — restricted users, MAC profiles, audit rules. Hours of setup, Linux-only, no semantic policy, brittle maintenance. Most people never attempt this.
3. wsh — two-minute setup, cross-platform, semantic policy enforcement, tamper-proof audit, cryptographically signed policies.

wsh isn’t competing with AppArmor — it’s filling a gap that didn’t exist until AI agents started running shell commands on our machines. In fact, our companion project warrant-box uses kernel-level isolation (Linux namespaces, seccomp, and AppArmor) alongside wsh to provide defence in depth: wsh handles semantic policy at the application layer, while warrant-box enforces hard containment at the kernel layer. They’re complementary, not competing.

Get started in two minutes → · Read the Manifest Standard →