AIShell-Gate — Interface Guide

Why This Guide Exists

AIShell-Gate is a policy-gated execution system that serves several distinct audiences: AI coding environments, operators running their own commands, CI pipelines, remote AI agents over SSH. The same binaries serve all of them, which is the architectural virtue — one policy engine, one audit chain, one mental model — but it means a new user looking at the doc set can find themselves staring at eight configuration paths and wondering which one applies to them.

This guide sorts the paths into three levels. Pick your level, follow its pointer, skip the rest.

Level	You are	Start here
Level 1	Using Claude Code or Cursor	MCP integration
Level 2	Running commands yourself, or driving from a script or local AI	Direct invocation
Level 3	Deploying to a production host, shared hosts, or remote AI	Remote deployment

Three levels, not nine. AIShell-Gate exposes several concrete interfaces — the launcher, the executor, the policy engine, MCP, SSH forced commands, the interactive modes. Each is documented in depth in its own guide. You do not need to understand all of them to start using the product. You need to pick one level, and the level tells you which guide to open.

Level 1 — Start Here If You Are a Developer

MCP Integration

You use Claude Code or Cursor. You want policy-gated execution without writing shell scripts. Ten minutes to a working setup.

What This Is

AIShell-Gate ships with an MCP server that exposes evaluate_plan and execute_plan as tools to Claude Code, Cursor, and any MCP-compatible AI coding environment. Your editor's AI discovers these tools automatically on restart. From then on, whenever the AI wants to run commands, it builds a JSON plan and submits it through the tools. Every command passes through policy. Every decision is audited.

What You Need to Do

Extract the AIShell-Gate tarball into a project directory.
Create aishell-mcp.json pointing at the three binaries with absolute paths.
Add an aishell-gate entry to your editor's .mcp.json.
Restart Claude Code or Cursor.

No root access. No SSH configuration. No Unix accounts to create. Nothing runs as a daemon.

Where to Go

INSTALL path A — step-by-step setup.
Getting Started Guide §2 — same setup with more context.
aishell-gate-mcp Using Guide — the full MCP tool reference (evaluate_plan, execute_plan, policy tools, and Enterprise-only tools).

Level 2 — Start Here If You Drive It Yourself

Direct Invocation

You run commands yourself, write scripts that call the gate, pipe JSON plans to it, or drive it from a local AI model. No SSH, no forced commands, no remote anything.

What This Is

Direct invocation means running the AIShell-Gate binaries yourself on your own machine. The same binaries serve several distinct use cases:

Use case	What you run	What it does
Educational assessment	`./aishell-gate-policy`	Interactive prompt. Type any command; see the policy decision, risk score, and documented flag reasoning. Never executes. Training and learning tool.
Interactive execution	`./aishell-gate`	Interactive prompt that also runs approved commands through `execve()`. Every command you type is evaluated, confirmed if required, and logged. Disciplined workflow for human operators.
JSON plan submission	`echo '{...}' \| ./aishell-gate`	Pipe a structured plan in; commands are evaluated and executed in sequence. The core programmatic interface.
Single-command policy check	`echo "cmd" \| ./aishell-gate-policy --json`	Get a machine-readable policy decision for a single command. No executor involved. Integration hook for CI pipelines, pre-commit hooks, regression test suites.
Local AI pipeline	Local model generates JSON, pipes to `aishell-gate`	Your local inference model (ollama, llama.cpp, any OpenAI-compatible endpoint) writes plans; the gate evaluates and executes them. The AI pipeline addendum documents this pattern.

What They Have in Common

Every row above uses the same policy engine, the same confirmation gates, and the same audit chain. The only thing that varies is who produces the command (a human, a script, a local model, a hand-written JSON file) and how they deliver it (interactive prompt, pipe, heredoc).

If you are not sure which use case fits: the interactive policy engine is where to start. It teaches you how the system evaluates commands without running anything.

The Educational Product

aishell-gate-policy's interactive mode is, by itself, a product worth using. For a junior operator learning Unix, it is a teaching tool that explains every flag in plain English at the moment the command is typed. For a senior operator in a regulated environment, it is a disciplined workflow with policy review and audit trail on every command — the same compliance properties the AI use case provides, applied to human activity. Both audiences are real. Neither requires any AI to be involved.

Where to Go

Getting Started Guide §6 — First Run: Interactive Mode. The shortest path to seeing the system work.
Getting Started Guide §9 — Running a Plan Through the Executor. The JSON plan format and how to submit plans.
Getting Started Guide §10 — Evaluating a Single Command. The scripting hook pattern.
AI Pipeline Addendum — the reference script for connecting a local inference model.

Level 3 — Start Here If You Are Deploying

Remote Deployment

An AI agent on one machine sends plans over SSH to a gate on another machine. Or multiple AI agents share a host. Or you need a human operator to confirm sensitive actions from a different terminal than the AI's.

What This Is

Remote deployment uses SSH with a forced command. An AI agent has an SSH key; that key's authorized_keys entry on the target host specifies aishell-gate as the forced command. Whatever the AI's SSH client requests, aishell-gate runs — reading the AI's JSON plan from stdin, evaluating against policy, optionally relaying confirmations through a separate operator terminal, and executing only what policy has approved.

This is the production deployment pattern. It is the same pattern git-shell, rsync, restic, and other Unix tools use for capability-scoped remote access. No new daemons, no new ports, no new infrastructure.

What It Adds Over Level 2

SSH as the transport — encrypted, identity-bound, key-revocable via removing a line from a file.
Dedicated AI account — a Unix user with no login shell, no writable home, and permissions scoped to exactly what the AI's work requires.
Forced command — the AI cannot request any binary other than aishell-gate.
Remote confirmation relay — when a confirmation fires, the AI sees nothing; the full context (command, goal, risk, challenge code) appears on an operator's separate SSH session via named FIFOs.
Multi-session support — multiple AI agents can share a host with audit-chain integrity and serialized confirmation.
Constrained account hardening — optional additional layer where the AI account has no PATH and no access to any binary except aishell-gate-exec. Policy governs what is permitted; the OS enforces what is reachable.

Where to Go

Remote Deployment Guide — the whole path, from SSH key generation through multi-session FIFO configuration to constrained account hardening. This is the dedicated document for Level 3.
INSTALL path C — the system-wide install required for shared-host use.

Scope: Remote Deployment Guide §11 (Remote Human Confirmation) is probably the most important single section for a new Level 3 deployer. It explains how confirmations flow in an environment where the AI has no terminal and the operator is in a different SSH session. Read it before going to production even if you are running single-session initially.

What's Not on This Map

Two interfaces exist but are not part of the three-level model:

The launcher as a future broker. Today aishell-gate is a thin pre-flight wrapper. In v2 it becomes a multi-agent, multi-operator broker. Using the launcher now means your configuration will not need to change when v2 ships. See Getting Started Guide §4.

Calling the gate from within bash scripts. An existing shell script can invoke aishell-gate per command to get policy evaluation and audit trail without rewriting the script's composition logic. This works and is occasionally useful, but it is not a promoted interface — the plan model is the designed API, and bash-wrapper use is better understood as a migration path for legacy scripts than as a first-class pattern.

When in doubt Level 1 if you are a Claude Code or Cursor user and want the shortest path to a working setup. Level 2 if you want to understand the system by driving it yourself. Level 3 if you are building something that will run in production. Most beta testers will spend most of their time at Level 1 and Level 2.