AISHELL-GATE(1)               AIShell-Gate Manual              AISHELL-GATE(1)


"AIShell-Gate" Copyright (c) 2026 AIShell Labs LLC Winston-Salem NC USA.
All Rights Reserved. Author: Sean T. Gilley
Do not remove this notice.
Use of this Software requires a valid license.

THIS SOFTWARE IS PROVIDED BY AISHELL LABS LLC "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL AISHELL LABS LLC BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

For full license terms see the LICENSE file or: www.aishellgate.com
                                                  


NAME
       aishell-gate  -  pre-flight launcher and stable entry point for
       AIShell-Gate

SYNOPSIS
       aishell-gate [exec-flags] [policy-flags]

       aishell-gate --policy-preset PRESET [--audit-log FILE] ...
       echo '<json-plan>' | aishell-gate --policy-preset PRESET

DESCRIPTION
       aishell-gate is the stable user-facing entry point to the
       AIShell-Gate system -- present and future.  Today it is a thin
       pre-flight wrapper around aishell-gate-exec(1).  In a future
       release it will become a multi-agent, multi-operator broker
       responsible for session coordination and confirmation routing.
       Because all invocations already flow through aishell-gate,
       that transition will require no changes to deployed SSH forced
       commands, MCP configurations, or user muscle memory.

       Use aishell-gate in preference to calling aishell-gate-exec
       directly.  aishell-gate runs pre-flight checks, injects the
       --policy-binary flag automatically based on environment, and
       hands off to the executor via exec(3).  It does not remain in
       the process tree after handoff.  All flags pass through to the
       executor unchanged.

   Pre-flight checks
       Before handing off, aishell-gate verifies:

       o  aishell-gate is not running as root.  Running as root is
          refused with a clean error before any executor code runs.

       o  Both aishell-gate-exec and aishell-gate-policy are present
          at their resolved paths and are executable.

       o  Neither binary is setuid or setgid.  A setuid or setgid
          binary in this position would create a local privilege
          escalation surface and is refused.

       Any failed check prints a clear error to standard error and
       exits with status 1 before the executor is invoked.  The audit
       log is not touched.

OPTIONS
       aishell-gate does not consume any flags of its own.  All
       arguments are passed through to aishell-gate-exec(1) unchanged.
       See aishell-gate-exec(1) for the full set of executor flags
       including --policy-preset, --policy-base, --policy-project,
       --policy-user, --audit-log, --jail-root, --safe-path, --dry-run,
       --interactive, --confirm-pipe, --confirm-lock, and others.

       aishell-gate itself has no edition of its own -- it is a thin
       pass-through wrapper present in both editions. Several of the
       flags it forwards are Enterprise-only: --policy-base,
       --policy-project, and the ci_build/ci_deploy/ci_admin/danger_zone
       --policy-preset values.
       See aishell-gate-exec(1) EDITIONS for the authoritative Standard/
       Enterprise split; this wrapper surfaces the same "not available
       in standard edition" error the executor would if an Enterprise-
       only flag is used on a Standard installation.

ENVIRONMENT
       aishell-gate resolves the aishell-gate-exec and aishell-gate-policy
       binaries relative to its own directory, so co-located binaries are
       found automatically with no configuration.  Two environment
       variables override the resolved paths:

       AISHELL_EXEC_BIN
              Path to the aishell-gate-exec binary.
              Default: aishell-gate-exec in the same directory as this
              script.

       AISHELL_POLICY_BIN
              Path to the aishell-gate-policy binary.  This path is
              passed to the executor as --policy-binary so callers
              never need to supply it explicitly.
              Default: aishell-gate-policy in the same directory as this
              script.

       Because the binaries are resolved relative to the script's own
       location, a system-wide install (whether under /usr/bin or
       /usr/local/bin) needs no configuration: the installed aishell-gate
       finds its co-located aishell-gate-exec and aishell-gate-policy
       automatically.  Set these variables only when the binaries live in
       a different directory than the aishell-gate script:

              AISHELL_EXEC_BIN=/opt/aishell/aishell-gate-exec \
              AISHELL_POLICY_BIN=/opt/aishell/aishell-gate-policy \
                  aishell-gate --policy-preset ops_safe

       For local-directory invocation -- typical during beta evaluation --
       no variables are needed when all three files sit together; just run
       the wrapper from that directory:

                  ./aishell-gate --policy-preset ops_safe

EXIT CODES
       aishell-gate emits a single exit code for any pre-flight
       failure.  After a successful pre-flight, control passes to
       aishell-gate-exec(1) via exec(3) and aishell-gate exits the
       process tree entirely; and any subsequent exit code is the
       executor's.

       1   Pre-flight failure.  The error message on standard error
           identifies the specific failure: running as root, exec
           binary missing or not executable, policy binary missing or
           not executable, or either binary is setuid or setgid.

       After exec(3) handoff, see aishell-gate-exec(1) for executor
       exit codes.

EXAMPLES
       Standard local invocation under a preset, no plan input
       (interactive mode auto-detected):
              aishell-gate --policy-preset ops_safe

       Pipe a JSON plan from stdin under the dev_sandbox preset:
              echo '{
                "goal": "show repo status",
                "actions": [{"type":"command","cmd":"git status"}]
              }' | aishell-gate --policy-preset dev_sandbox

       Dry run with audit log -- evaluates policy, fires confirmation
       gates, but does not execute:
              aishell-gate --policy-preset ops_safe \
                  --audit-log ./exec.jsonl --dry-run

       Layer custom policy files on top of a preset:  [ENTERPRISE]
              aishell-gate --policy-preset dev_sandbox \
                  --policy-project ./project.json \
                  --policy-user ./user.json

       SSH forced command for remote deployment (in authorized_keys):
              command="/usr/local/bin/aishell-gate \
                  --policy-preset ops_safe \
                  --confirm-pipe /run/aishell-gate/confirm \
                  --confirm-lock /run/aishell-gate/confirm.lock \
                  --audit-log /var/log/aishell/audit.log",\
              no-port-forwarding,no-agent-forwarding,no-X11-forwarding \
              ssh-rsa AAAA...

       Local-directory invocation during beta evaluation:
              AISHELL_EXEC_BIN=./aishell-gate-exec \
              AISHELL_POLICY_BIN=./aishell-gate-policy \
                  ./aishell-gate --policy-preset ops_safe

WHY USE AISHELL-GATE.SH
       Calling aishell-gate-exec directly works -- aishell-gate is not
       in any execution-critical path -- but it exists for three
       concrete reasons:

       o  The pre-flight checks are real safety value.  Running as
          root or with a setuid binary is refused before the executor
          ever opens a file.

       o  The --policy-binary flag is injected automatically.  Callers
          and SSH forced commands do not need to know where the policy
          engine lives; they just invoke aishell-gate.

       o  aishell-gate is the stable entry point.  In a future
          release the system becomes a multi-agent broker.  Today's
          invocations will continue to work without modification.

SEE ALSO
       aishell-gate-exec(1) -- the executor aishell-gate hands off to;
                               full flag reference, exit codes, the
                               Standard/Enterprise edition split, and the
                               aishell-gate-confirm relay flags/exit codes
       aishell-gate-policy(1) -- the policy engine; policy file format,
                               presets, and the interactive mode

       Getting Started Guide  -- aishell-gate is documented in the
                               section of the same name
       Remote Deployment Guide

AUTHOR
       Sean T. Gilley

VERSION
       aishell-gate 0.4.0
    

AIShell-Gate                      April 2026                   AISHELL-GATE(1)
