agentvigilante

Demo

Video walkthrough coming soon.

The problem

Coding agents run shell commands. Most of the time that is pytest and npm install. Occasionally it is rm -rf, a rewritten .env, or a package that phones home.

You find out afterward.

What AgentVigilante does

Every command is classified before it executes, runs against a copy-on-write clone of your workspace inside an ephemeral container, and only reaches your real files when you say so.

Install (one command)

Requirements: Python 3.11+, Docker Desktop (or Engine) running, host git.

# Python (recommended)
pipx install agentvigilante && agentvigilante bootstrap

# or npm
npx agentvigilante bootstrap

# or Homebrew (after the tap is published)
brew install adityalone/tap/agentvigilante && agentvigilante bootstrap

Then start the console:

agentvigilante start          # → http://127.0.0.1:8420

bootstrap checks your environment, builds the sandbox image, and wires Cursor / Claude / Windsurf MCP configs. Restart your IDE after bootstrap so the MCP tools load.

Maintainer release steps: see PUBLISH.md.

Try a risky command

curl -s http://127.0.0.1:8420/v1/commands \
  -H 'Content-Type: application/json' \
  -d '{"command":"echo hello > greeting.txt","timeout":10}'

That write appears in the console — and as a native dialog — waiting for Approve or Deny.

How it works

flowchart TD
  agent[Agent command]
  analyzer[AST risk analyzer]
  blocked[Blocked with feedback]
  pending[Pending your approval]
  hologram[COW shadow workspace]
  docker["Docker sandbox + strace"]
  egress[Whitelist CONNECT proxy]
  promote[Promote to real workspace]

  agent --> analyzer
  analyzer -->|CRITICAL| blocked
  analyzer -->|RISKY| pending
  analyzer -->|SAFE| hologram
  pending -->|Approve| hologram
  hologram --> docker
  docker --> egress
  docker --> promote

1. Classify — a bashlex AST pass sorts every command into SAFE, RISKY, or CRITICAL.
2. Clone — the job gets a copy-on-write shadow of your workspace. Docker mounts the shadow, never the origin.
3. Contain — non-root container, CPU/memory caps, pids_limit=64, cap_drop=ALL, destroyed after the turn.
4. Filter — outbound traffic passes a whitelist CONNECT proxy; DNS inside the sandbox is blackholed.
5. Decide — approve, deny with feedback, promote the diff, or revert the hologram and the agent's memory with it.

Three ways to route agents through AgentVigilante

MCP gateway

agentvigilante init              # patches Claude / Cursor / Windsurf
agentvigilante init --project    # also ./.cursor/mcp.json

Tools exposed: agentvigilante_exec, agentvigilante_job_status, agentvigilante_revert.

{
  "mcpServers": {
    "agentvigilante": {
      "command": "python",
      "args": ["-m", "agent_vigilante.mcp_server"],
      "env": { "AGENTVIGILANTE_URL": "http://127.0.0.1:8420" }
    }
  }
}

PATH shims (agentvigilante wrap)

MCP is a soft boundary — the model can still reach for a built-in Shell tool. Wrapping is harder: shims in ~/.agentvigilante/shims intercept the binary lookup itself.

agentvigilante shim-install
agentvigilante wrap claude       # CLI agents
agentvigilante wrap cursor .     # launches Cursor with shimmed PATH (macOS)

wrap prepends the shim directory to PATH, points SHELL at the shimmed shell, and launches GUI apps by their binary so the environment survives. Set AGENTVIGILANTE_BYPASS=1 for deliberate host passthrough.

Residual risk: an absolute invocation such as /bin/zsh -c ... skips PATH entirely and is not intercepted.

Invisible mode

Interactive is the default. Invisible mode is for when you want the guard running without the ceremony.

agentvigilante invisible enable     # background service + shell PATH + autopilot
agentvigilante invisible status
agentvigilante invisible disable    # back to interactive

Autopilot is what keeps it quiet: standard development commands run straight through the sandbox, and you are only interrupted by anomalies — sensitive-path writes, global installs, git push, destructive patterns.

Service control on its own:

agentvigilante service install | uninstall | status | start | stop

IDE extension

extensions/vscode/ adds a status bar item — AgentVigilante: Active (0 pending) — with one-click Approve / Block when something needs you. Install instructions live in that folder.

Security model

Risk routing

Defense in depth

1. Pre-flight AST analyzer (bashlex) — classification before execution
2. Human in the loop — approve, deny with feedback, or deny and revert
3. Docker isolation — non-root 1000:1000, memory/CPU caps, pids_limit=64, cap_drop=ALL (+ SYS_PTRACE for tracing), no-new-privileges, ephemeral
4. Whitelist CONNECT egress — allowed hosts only, no TLS interception
5. DNS blackhole — dns=127.0.0.1 inside the container; registry hosts pinned via extra_hosts
6. Symlink guard — SAFE commands touching workspace symlinks escalate to review and are rechecked at approve time
7. Git Time Machine — checkpoints under refs/agentvigilante/* inside the hologram
8. Memory revert — wiping the shadow also injects a one-shot SYSTEM OVERRIDE so the model stops believing its change landed

Egress whitelist

pypi.org, files.pythonhosted.org, registry.npmjs.org, github.com, objects.githubusercontent.com, nodejs.org and their subdomains.

Containers get HTTP(S)_PROXY=http://host.docker.internal:8888. Clients that honor the proxy are filtered at CONNECT.

Residual risk: raw TCP to literal IPs, and tools that ignore HTTP_PROXY (curl --noproxy '*'), can still leave via the Docker bridge until an iptables sidecar lands. Treat Approve as a privileged action.

Console

The UI is a Vite + React + shadcn app in web/: landing at /, containment console at /console.

Approve or deny pending commands, stream live terminal output over WebSocket, inspect filesystem diffs, review kernel telemetry from strace -f, promote a hologram into your real workspace, or hit E-Stop.

cd web
npm install
npm run build      # outputs web/dist, served by FastAPI
npm run dev        # optional live reload on :5173

API

# SAFE — auto-executes
curl -s http://127.0.0.1:8420/v1/commands \
  -H 'Content-Type: application/json' \
  -d '{"command":"ls -la","timeout":10}'

# RISKY — pending approval
curl -s http://127.0.0.1:8420/v1/commands \
  -H 'Content-Type: application/json' \
  -d '{"command":"echo hello > greeting.txt","timeout":10}'

curl -s -X POST "http://127.0.0.1:8420/v1/commands/${JOB_ID}/approve"
curl -s "http://127.0.0.1:8420/v1/commands/${JOB_ID}"

# Runtime state for IDE integrations
curl -s http://127.0.0.1:8420/v1/status
curl -s http://127.0.0.1:8420/v1/events/recent

# Egress log and emergency stop
curl -s http://127.0.0.1:8420/v1/egress/events
curl -s -X POST http://127.0.0.1:8420/v1/estop

Development

git clone https://github.com/ADITYALONE/AgentVigilante.git
cd AgentVigilante

python3 -m venv .venv && source .venv/bin/activate
pip install -e .
./scripts/sync_web_assets.sh   # optional — rebuilds packaged UI
agentvigilante bootstrap
agentvigilante start

Run the suite:

python -m unittest discover -s tests -v

agent_vigilante/
├── cli.py                # init / setup / start / wrap / invisible / service
├── config.py             # ~/.agentvigilante/config.json
├── shim.py               # PATH shim generation
├── exec_shim.py          # shim → daemon client
├── wrap.py               # environment composition and app launch
├── service.py            # launchd / systemd units
├── shell_integration.py  # .zshrc / .bashrc injection
├── notify.py             # native Approve / Deny dialogs
├── mcp_server.py         # MCP stdio server
├── core/
│   ├── command_analyzer.py   # AST risk classification
│   ├── autopilot.py          # silent-run allowlist
│   ├── hologram.py           # COW shadow workspaces
│   ├── isolation.py          # Docker sandbox
│   ├── egress_proxy.py       # whitelist CONNECT proxy
│   ├── checkpoint.py         # git Time Machine
│   ├── path_guard.py         # symlink guard
│   ├── strace_profile.py     # kernel telemetry
│   ├── diff_engine.py
│   └── proxy.py              # FastAPI routes
├── dashboard/server.py
extensions/vscode/        # Cursor / VS Code status bar
web/                      # Vite + React console
tests/

Distribution

Contributing

Issues and PRs are welcome — start with CONTRIBUTING.md. Because this is a security tool, every PR states its security impact, even when that impact is none.

Found a bypass? Email adityapunjani9@gmail.com instead of opening a public issue.

License

MIT © Aditya Punjani