
AIShell-Gate
============

AIShell Labs LLC — www.aishellgate.com
Copyright 2026 AIShell Labs LLC. All Rights Reserved.

------------------------------------------------------------------------

AIShell-Gate evaluates shell commands against a policy before they run.
It is a risk-reduction tool — not a security guarantee and not a
standalone security product — and provides no warranty of fitness for
any particular purpose; see the LICENSE for full terms. AIShell-Gate's 
primary use it to allow a remote AI to ssh into a linux server and use
that server in a controlled manner through AIShell-Gate exclusively. 
An MCP server is also available.
------------------------------------------------------------------------

!! BETA RELEASE !!

This is a beta release. Do not use on production systems. Read the
beta notice and safety guidance at the top of the Getting Started
Guide (docs/AIShell_Gate_Getting_Started.html) before running
anything.

------------------------------------------------------------------------

START HERE

docs/AIShell_Gate_Getting_Started.html — orientation, setup, and
first use. The starting point for everything in this package.

------------------------------------------------------------------------

QUICK CHECK

Confirm the two binaries work before reading further. From <package>/bin,
evaluate a harmless command in dry-run mode (nothing is executed):

  echo '{"goal":"smoke test","actions":[{"type":"command","cmd":"ls"}]}' \
    | ./aishell-gate --policy-preset read_only --dry-run

Expect an ALLOW summary for "ls" and a final line ending
"(execution suppressed)". If you see that, the gate is wired up
correctly. See the Getting Started Guide for real (non-dry-run) use.

------------------------------------------------------------------------

PACKAGE LAYOUT

<package>/          README.txt, LICENSE.txt, NOTICES.txt
                    aishell-gate-install.sh  Optional installer (see INSTALL
                                             SCRIPTS below). The manual setup in
                                             the Getting Started Guide needs none
                                             of this.

<package>/bin       Two binaries:
                      aishell-gate-policy   Policy engine
                      aishell-gate-exec     Execution gateway
                    Five scripts:
                      aishell-gate              Pre-flight wrapper and stable
                                                entry point
                      aishell-gate-confirm      Operator confirmation relay
                      aishell-gate-curl.sh      Smallest API connectivity demo
                      aishell-gate-pipe.sh      AI-generated plan, piped through
                                                the gate
                      aishell-gate-chat.py      Conversational AI terminal client

<package>/bin/MCP   MCP server and its setup files. Start with README_MCP.txt.
                      aishell-gate-mcp        MCP server (Python; needs python3)
                                              for Claude Code, Cursor, and other
                                              MCP-compatible environments
                      aishell-gate-mcp-install.sh
                                              Optional: stages the files below into
                                              a project for you (see INSTALL
                                              SCRIPTS). Doing it by hand works just
                                              as well.
                      aishell-gate-mcp.json   Gate configuration. Copy to your
                                              project root.
                      dot_mcp.json            Template for .mcp.json. Copy to your
                                              project root and rename to .mcp.json.
                      CLAUDE.md               Usage guide for the AI. Copy to
                                              aishell-gate/CLAUDE.md in your project.
                      settings.json           Template for .claude/settings.json
                      README_MCP.txt          MCP setup walkthrough

<package>/docs      HTML guides:
                      AIShell_Gate_Getting_Started.html   Start here
                      AIShell_Gate_Using_MCP.html         MCP / Claude Code / Cursor
                      AIShell_Gate_Remote_Howto.html      Remote SSH deployment
                      AIShell_Gate_White_Paper.html       Design and rationale
                      aishell-gate-beta-test-plan.html    Beta test plan

                    Plain-text man pages. Read with less, man -l FILE,
                    or any text viewer.
                      aishell-gate-policy-manpage    Policy engine — all flags,
                                                     policy file format, presets,
                                                     sandbox modes, audit options,
                                                     exit codes
                      aishell-gate-exec-manpage      Executor — plan format, all
                                                     flags, execution model, audit
                                                     log events, exit codes, plus
                                                     the confirmation relay flags
                                                     and exit codes
                      aishell-gate-manpage           aishell-gate — pre-flight
                                                     checks, environment overrides,
                                                     SSH forced command examples
                      aishell-gate-confirm-manpage   Operator confirmation relay —
                                                     flags, FIFO model, exit codes

------------------------------------------------------------------------

INSTALL SCRIPTS (OPTIONAL)

The package ships a few shell scripts that automate the setup steps
described by hand in the Getting Started and MCP guides. They are a
convenience, not a requirement: everything they do, you can do yourself
by copying files as the guides describe. If you prefer not to run
install scripts, skip this section entirely — nothing else depends on it.

  aishell-gate-install.sh   (package root)
      System-wide install. Run as root; copies the two binaries, the
      aishell-gate wrapper, and the MCP server to /usr/local/bin so every
      user on the machine can use them, then hands off to
      aishell-gate-mcp-install.sh to wire up a project. Needs root only
      because /usr/local/bin does. Install is not required. The package 
      can be run from any unzipped directory.

        sudo ./aishell-gate-install.sh --project /path/to/your/project

  bin/MCP/aishell-gate-mcp-install.sh
      Stages the four project files (aishell-gate-mcp.json, .mcp.json,
      CLAUDE.md, settings.json) into a Claude project. No root. Asks
      which project to set up, or takes --project. Never overwrites a
      file you already have.

        ./bin/MCP/aishell-gate-mcp-install.sh --project /path/to/your/project

  A network installer is also published at
  www.aishellgate.com/aishell-gate-network-install.sh for those who want
  a one-line "curl | sh" setup. It does the same as the two scripts
  above, without root, running the MCP server in place from
  ~/aishell-gate/. It is entirely optional; if you would rather not pipe
  a script from the web into your shell, the manual steps in the guides —
  or the two scripts above — get you to the same place.

RELOCATING A NO-ROOT INSTALL

  If you do not root install the package system wide you can still use the
system from its install director. Beaware that the MCP server 
  finds the aishell-gate binaries relative to where it sits. If you
  move the unpacked ~/aishell-gate/ directory elsewhere it keeps working. 
  But Each wired project's .mcp.json, however, records the
  server's path as installed. If you relocate the install, you can break 
.mcp.json. S either put aishell-gate-mcp
  on the system PATH (the launcher checks PATH first) or update that path
  in each project's .mcp.json.

------------------------------------------------------------------------

REPORTING AND FEEDBACK

Contact: info@aishellgate.com

General feedback and test results
  www.aishellgate.com/feedback.html


Security vulnerabilities (private disclosure only)
  security@aishellgate.com
  Private email only — do not use public GitHub issues for security
  reports.

Channel partner inquiries (MSPs, MSSPs, VARs, integrators)
  partners@aishellgate.com

------------------------------------------------------------------------

LICENSE

See the LICENSE.txt file distributed with the software for full terms.

"AIShell-Gate" Copyright (c) 2026 AIShell Labs LLC Winston-Salem NC USA.
All Rights Reserved. Use of this Software requires a valid license.

www.aishellgate.com
