A deterministic policy layer that mediates between probabilistic AI systems and deterministic Unix infrastructure. Every AI-generated command passes through a policy gate before execution — never through a shell.
Large language models are increasingly used to generate shell commands. They are good at it. They are also probabilistic. Unix execution, by contrast, is deterministic and irreversible — a single misplaced flag or path can permanently alter system state.
AIShell-Gate exists to close that gap. It sits between an AI agent's proposed actions and the operating system, evaluating every command against declared policy before a single byte reaches the kernel. Unsafe commands are denied with a reason. Safe commands are allowed — with a confirmation level appropriate to their risk. No shell is ever invoked.
The separation between the two programs is the central security property of the system. The executor has no policy logic; the policy engine has no ability to execute. Neither component can reach across that boundary.
Receives a proposed shell command, normalizes it, evaluates it against a layered policy stack, computes a risk score, and emits a structured JSON decision. It never executes anything. Its only output is the decision record: allow or deny, confirmation level, matched rule and layer, validated argument array, risk score, blast radius, and reason.
Accepts a JSON action plan from an AI agent, submits each command to the policy engine as a child process, reads the JSON decision back over a pipe, collects human confirmation where the policy requires it, and calls execve() with the validated argument vector. Contains no policy logic of its own.
Policy is a stack of three layers evaluated in order: base (organizational floor), project (workflow-specific rules), and user (personal preferences). A deny at any layer is final. The built-in presets — ops_safe, dev_sandbox, read_only, danger_zone — give teams a working starting posture without manually assembling policy files.
Every ALLOW decision carries a confirmation level: none (proceed immediately), plan (show the plan before running), action (explicit per-command approval), or typed (operator must type a code derived from the exact command). Risk scoring escalates levels automatically — commands scoring above 40, 70, or 90 are raised to plan, action, or typed regardless of what the matching rule says. Levels can only be raised, never lowered.
Every evaluation can be written to a tamper-evident JSON Lines audit log. Each entry carries a sequence number, session identifier, full decision context, and an SHA-256 hash linking it to the preceding entry. HMAC-SHA256 mode restricts verification to key-holders. Concurrent sessions write safely via advisory file locking.
The following documents are included with this release. All are available in the same directory.
ai-agent account, directory and permission setup, and operator confirmation relay configuration.AIShell-Gate Binary Beta Release will soon be available as a public beta. Documentation is available now from the links above. The core architecture is stable. The policy model is functional. The goal of the beta phase is to gather real-world usage patterns, policy design feedback, integration experience, and edge cases that only surface in practice.
The beta package contains both compiled binaries, all documentation, and the beta README.
Beta scope: the beta is intended for local and single-session use by technically experienced Unix engineers, DevOps teams, and security engineers. Testing should be performed in controlled, non-production environments.