runok

Command Allowlisting

Define exactly which commands are allowed. Everything else is denied by default.

Pattern Matching

Wildcards, placeholders, and alternation to match commands precisely.

Sandbox Execution

Run allowed commands in a restricted environment with filesystem and network isolation.

Why runok?

Claude Code’s built-in permissions use simple glob matching. This works for basic cases, but breaks down quickly.

Text-based parsing causes false positives. Even when git log is in your allow list, Claude adds a comment and you get prompted:

⏺ Bash(# check logs
      git log --oneline -5)

Command contains newlines that could separate multiple commands

runok uses tree-sitter-bash to parse commands into an AST, so comments, compound commands, and other shell constructs are handled correctly.

Denied commands give no explanation. The agent cannot learn why a command was blocked. With runok, deny rules include a message and a suggested fix:

runok.yml

- deny: 'git push -f|--force *'
  message: 'Force push is not allowed.'
  fix_suggestion: 'git push --force-with-lease'

Global flags break matching. git -C /path commit does not match git commit *. runok supports optional groups, alternation, and order-independent matching:

runok.yml

- allow: 'git [-C *] commit *'
# matches both "git commit" and "git -C /path commit"

Read the full comparison →

How it works

Define allowed commands in runok.yml:

rules:
  - allow: "git push|pull|fetch **"
  - allow: "npm install|test|run **"
  - deny: "rm -rf /"

Then use runok to check or execute commands:

$ runok check "git push origin main"
# ✅ allowed

$ runok check "rm -rf /"
# ❌ denied

$ runok exec "npm test"
# runs in a sandboxed environment

Explore the docs

Getting Started

Install runok and set up your first configuration.

Why runok? | Installation | Quick Start | Claude Code

Configuration

Full reference for runok.yml configuration options.

Configuration Reference

Pattern Syntax

Learn the pattern syntax for matching commands.

Pattern Syntax Reference

CLI Reference

Reference for runok check, runok exec, and other commands.

CLI Reference

Recipes Practical configuration examples for common use cases.

Troubleshooting Common issues and debugging tips.