Running a Remote AI Through
AIShell-Gate Using SSH

01 Overview

This guide explains how to allow an AI system running on one machine to submit controlled command plans for execution on another machine using AIShell-Gate.

The goal is not to give the AI a shell. Instead, the AI submits a structured JSON plan that passes through a policy gate before any command is executed. This preserves security while still allowing meaningful automation.

02 Architecture

The Two-Binary Design

AIShell-Gate consists of two cooperating binaries with strictly separated responsibilities:

• aishell-gate-policy — the policy evaluation engine. Accepts a command description, evaluates it against configured policy, and returns a structured JSON decision. It never executes anything.
• aishell-gate-exec — the execution harness. Reads a JSON plan from the AI, submits each action to aishell-gate-policy as a child process, collects any required human confirmation, and calls execve() with the validated argument vector. It contains no policy logic of its own.

This separation is the central security property of the system. The executor cannot approve or deny a command; only the policy engine can, and it does so in a separate process.

Deployment Flow

Security Layers

The design creates multiple independent security boundaries. Even if one layer fails, the others continue to protect the system.

03 Installation

Both binaries must be present on the machine that will execute commands. The executor calls the policy engine as a subprocess, so both must be reachable.

Recommended locations:

/usr/local/bin/aishell-gate-policy
/usr/local/bin/aishell-gate-exec

Ensure both are executable:

chmod 755 /usr/local/bin/aishell-gate-policy
chmod 755 /usr/local/bin/aishell-gate-exec

04 SSH Configuration

Create a Dedicated AI User

Create an account whose sole purpose is to receive AI command plans via SSH:

useradd -r -s /bin/false ai-agent

This account has no interactive login shell and no home directory access. It exists only to receive the forced SSH command.

Configure the Forced Command

Edit ~ai-agent/.ssh/authorized_keys and add the AI's public key with a forced command:

command="/usr/local/bin/aishell-gate-exec \
  --policy /usr/local/bin/aishell-gate-policy \
  --preset ops_safe \
  --audit-log /var/log/aishell_ai.log",\
no-port-forwarding,no-agent-forwarding,no-X11-forwarding \
ssh-rsa AAAA...

With this in place, any SSH connection from the AI — regardless of what command the client requests — will run aishell-gate-exec with the specified options. The AI cannot bypass the gate.

Commonly Used Flags

Less common policy engine flags that aishell-gate-exec does not recognise natively can be passed after a -- separator in the forced command:

command="/usr/local/bin/aishell-gate-exec \
  --policy /usr/local/bin/aishell-gate-policy \
  --preset ops_safe -- --mode batch"

05 JSON Plan Format

aishell-gate-exec reads a JSON plan from standard input. The plan describes the AI's goal and the list of actions to carry out. The only required field is actions.

{
  "goal":    "check disk usage and list recent logs",
  "source":  "ai",
  "actions": [
    {"cmd": "df -h"},
    {"cmd": "ls -lt /var/log"}
  ]
}

Commands are given as a single cmd string — arguments are not supplied separately. aishell-gate-policy tokenizes the command string and produces a validated argument vector. aishell-gate-exec passes that vector to execve() directly, without invoking a shell.

06 Sending Plans

The AI sends its plan over SSH via standard input:

ssh ai-agent@server <<'EOF'
{
  "goal":    "check disk usage and list recent logs",
  "source":  "ai",
  "actions": [
    {"cmd": "df -h"},
    {"cmd": "ls -lt /var/log"}
  ]
}
EOF

The forced command defined in authorized_keys intercepts the connection. The AI's plan arrives on the stdin of aishell-gate-exec. Whatever the SSH client requested is ignored.

07 Policy Decisions

For each action in the plan, aishell-gate-exec submits the command to aishell-gate-policy as a child process and reads back a structured JSON decision. Key fields in that decision:

If the decision is DENY, the action is refused and the reason is reported. If the decision is ALLOW, the executor proceeds according to the confirmation level.

08 Confirmation Levels

Some commands require a human operator to confirm before execution. This is a policy decision — neither the AI nor the executor controls it. Confirmation for all actions is collected in a single pass before any command runs, so a mid-plan refusal cannot leave the system in a partially-executed state.

By default, aishell-gate-exec opens /dev/tty for confirmation prompts — the controlling terminal of the process, separate from stdin. This works correctly in any interactive session.

09 Remote Human Confirmation

When the AI operates over SSH and the policy engine requires a human confirmation, the question is: where does the prompt appear, and how does the operator answer it? The --confirm-pipe flag, combined with the aishell-confirm companion tool, provides the secure answer.

How it works

The operator opens a second SSH session to the remote host and runs aishell-confirm. That tool creates two named FIFOs — confirm.req and confirm.resp — owned by the operator with a shared group. When a confirmation fires, aishell-gate-exec writes a JSON request to confirm.req containing the full command context: command text, goal, source, risk score, blast radius, policy reason, and challenge code for typed confirmations. aishell-confirm reads it, displays everything on the operator's terminal, reads the operator's response, and writes it back through confirm.resp. The ai-agent account never opens any PTY device.

Step-by-step setup

Step 1 — One-time: create a shared group and the runtime directory.

The confirmation FIFOs must be accessible by both the operator and the ai-agent account. The cleanest model is a dedicated shared group:

# Create shared group and add both accounts
sudo groupadd aishell-gate
sudo usermod -aG aishell-gate operator
sudo usermod -aG aishell-gate ai-agent

# Create the runtime directory with the shared group and setgid bit
sudo mkdir -p /run/aishell-gate
sudo chown root:aishell-gate /run/aishell-gate
sudo chmod 2770 /run/aishell-gate   # setgid: new files inherit aishell-gate group

With this in place, aishell-confirm (running as the operator) creates FIFOs with mode 0660 and group aishell-gate. aishell-gate-exec (running as ai-agent, a member of aishell-gate) can open them for reading and writing. Neither account needs PTY group membership.

Step 1b — Make the directory survive reboots.

/run is a tmpfs memory filesystem on virtually every modern Linux system — it is created fresh on every boot. Without action, /run/aishell-gate/ disappears at shutdown. On the first AI connection after a reboot, aishell-gate-exec will fail to open the lock file, exit with code 5, and refuse all plans. On systemd systems, a tmpfiles.d drop-in recreates the directory automatically before sshd starts:

sudo tee /etc/tmpfiles.d/aishell-gate.conf <<'EOF'
d /run/aishell-gate 2770 root aishell-gate -
EOF
sudo systemd-tmpfiles --create /etc/tmpfiles.d/aishell-gate.conf
ls -ld /run/aishell-gate   # verify: should show drwxrws--- root aishell-gate

Step 2 — Each session: operator arms the relay with aishell-confirm.

# Operator's own SSH session — keep this window open
ssh operator@remotehost
$ aishell-confirm
[aishell-confirm] Terminal:  /dev/pts/3
[aishell-confirm] Req  FIFO: /run/aishell-gate/confirm.req
[aishell-confirm] Resp FIFO: /run/aishell-gate/confirm.resp
[aishell-confirm] Status:    armed — waiting for confirmation requests
[aishell-confirm] Press Ctrl-C to disarm.

# Full confirmation requests will appear here as the AI submits plans

Step 3 — Add --confirm-pipe and --confirm-lock to the forced command in authorized_keys.

command="/usr/local/bin/aishell-gate-exec \
  --policy /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...

Step 4 — AI submits a plan that triggers a confirmation. The operator sees the full context on their terminal:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  AISHELL-GATE CONFIRMATION REQUEST
  Session:  a3f8c21d9e4b7012...
  Action:   0   Level: action
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Command:  git push origin main
  Goal:     deploy release v2.4.1
  Source:   ai
  Reason:   modifies remote branch; requires explicit approval
  Risk:     72/100   blast=system
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Approve? [yes/NO]

The operator types yes (or anything else to refuse). The AI's SSH session receives the result immediately.

For confirm: typed (high-risk commands), the challenge code is displayed here — on the operator's terminal only — and the operator must type it back exactly:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  AISHELL-GATE CONFIRMATION REQUEST
  Session:  a3f8c21d9e4b7012...
  Action:   1   Level: typed
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Command:  rm -rf /var/tmp/old-builds
  Goal:     clean build artifacts
  Source:   ai
  Reason:   recursive delete; high blast radius
  Risk:     91/100   blast=system

  ⚠  HIGH-RISK — typed confirmation required.
  Type the challenge code exactly to confirm:
  Challenge: 3k7mw2nx
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Type code: 

The challenge code is derived from the exact command text. It is sent only through the pipe to the operator's terminal — it never appears in the AI's SSH channel. aishell-gate-exec verifies the operator's typed response independently.

What happens when the relay is not armed

If aishell-confirm is not running when a confirmation fires, aishell-gate-exec will find no reader on the request FIFO and fail immediately with exit code 5:

[gate-exec] ERROR: confirmation request pipe '/run/aishell-gate/confirm.req' has no reader.
[gate-exec]   aishell-confirm is not running in an operator session.
[gate-exec]   Start it: ssh operator@host  then run: aishell-confirm
[gate-exec]   No commands have been executed.

The AI receives exit code 5, the audit log records the failure, and no commands run. The operator needs to start aishell-confirm before the AI tries again.

Multiple concurrent AI sessions

Multiple concurrent AI sessions share the same FIFO pair. The --confirm-lock flag serialises the confirmation phase: only one aishell-gate-exec session can write to confirm.req and read from confirm.resp at a time. Other sessions block on the lock until the current session finishes. The lock is released before any execve() call, so command execution across sessions still proceeds in parallel. Without the lock, concurrent sessions would interleave their JSON frames on the shared FIFOs, producing unparseable requests.

Single-session interactive deployments

For a single operator running a single AI session on a machine they are logged into interactively, no special setup is required. aishell-gate-exec opens /dev/tty by default and prompts directly on the controlling terminal. --confirm-tty is available for the rare case where the operator wants to redirect prompts to a specific device. Neither --confirm-pipe nor --confirm-lock is needed in this scenario.

10 Complete Examples

Read-Only Monitoring

Policy preset read_only. No confirmation required for listing and reading operations.

# Forced command in authorized_keys:
# command="/usr/local/bin/aishell-gate-exec \
#   --policy /usr/local/bin/aishell-gate-policy \
#   --preset read_only \
#   --audit-log /var/log/aishell_ai.log"

# AI sends this plan:
ssh ai-agent@server <<'EOF'
{
  "goal":    "check system health",
  "source":  "monitoring-agent",
  "actions": [
    {"cmd": "uptime"},
    {"cmd": "df -h /"},
    {"cmd": "free -m"}
  ]
}
EOF

Operations Work with a Jail Root

Policy preset ops_safe. The --jail-root flag restricts write-class commands to the specified directory tree.

# Forced command in authorized_keys:
# command="/usr/local/bin/aishell-gate-exec \
#   --policy /usr/local/bin/aishell-gate-policy \
#   --preset ops_safe \
#   --jail-root /srv/deployments \
#   --audit-log /var/log/aishell_ai.log"

# AI sends this plan:
ssh ai-agent@server <<'EOF'
{
  "goal":     "deploy updated configuration",
  "source":   "deploy-agent",
  "strategy": "fail_fast",
  "actions":  [
    {"cmd": "cp /srv/deployments/staging/app.conf /srv/deployments/prod/app.conf"},
    {"cmd": "systemctl reload myapp"}
  ]
}
EOF

Development Sandbox

Policy preset dev_sandbox allows a broader set of operations within a workspace. Using best_effort strategy so that a test failure does not prevent subsequent steps from running.

ssh ai-agent@devserver <<'EOF'
{
  "goal":     "update dependencies and run tests",
  "source":   "ci-agent",
  "strategy": "best_effort",
  "actions":  [
    {"cmd": "git pull"},
    {"cmd": "npm install"},
    {"cmd": "npm test"}
  ]
}
EOF

11 Security Considerations

Never Expose a Shell

The ai-agent account has /bin/false as its shell and the authorized_keys entry forces aishell-gate-exec for every connection. There is no path through which the AI can obtain an interactive shell.

Environment Variables

SSH may pass environment variables into the session. aishell-gate-exec sanitizes its execution environment and does not pass the ambient environment to child processes. Use no-user-rc and no-agent-forwarding in authorized_keys as additional precautions.

Binary Integrity

aishell-gate-exec checks at startup that neither it nor the aishell-gate-policy binary is setuid or setgid. If either check fails, execution halts immediately and the violation is written to the audit trail before exit. Keep both binaries owned by root and not world-writable.

No Shell Execution

aishell-gate-policy tokenizes the command string itself and returns a validated argv array. aishell-gate-exec passes that array to execve() directly. No shell is invoked at any point. Shell metacharacters in a command string are inert — any command that tries to exploit them will be evaluated against policy on its literal terms.

Least Privilege

The ai-agent account should have the minimum permissions required for the AI's work: access to specific paths, no sudo, no writable home directory, no membership in privileged groups.

Audit Logging

Specify --audit-log in the forced command so every plan submission is recorded. The executor log captures the plan source, each action, the policy engine decision, confirmation outcome, and execution result. The policy engine has its own separate audit log (--audit flag) that supports HMAC-SHA256 tamper-evident chaining for cryptographic log integrity when that level of assurance is required.

Each aishell-gate-exec invocation is an independent process with its own HMAC chain state. When multiple AI sessions write to the same audit log file, the file contains one internally consistent HMAC chain per session_id, not a single global sequence. When verifying chains, always operate per session_id; treating the entire log as a single linear sequence will produce false verification failures when sessions are concurrent.

For the HMAC chain to remain verifiable across restarts and sessions, a persistent key must be configured. Without one, each invocation generates a random per-session key that is discarded on exit, making post-hoc chain verification impossible. Configure a persistent key by one of these methods, in priority order:

1. Set the AISHELL_AUDIT_KEY environment variable to a 64-character hex string (32 raw bytes) in the forced command environment.
2. Create /etc/aishell/audit.key containing a 64-character hex string on the first line, readable by the ai-agent account. Mode 0640 with group ai-agent is appropriate.

If neither is configured, aishell-gate-exec emits a warning to stderr at startup. In a multi-session deployment this warning appears in the stderr of each AI's SSH session; if those streams are not monitored, the degraded mode may go unnoticed. The warning text includes the word ephemeral to make it grep-friendly in log aggregation.

Concurrent AI Sessions

Allowing multiple AI agents to connect simultaneously requires two mitigations: the --confirm-pipe / --confirm-lock combination described in § 09, and a persistent HMAC key for audit chain integrity as described above. Neither is required in a single-session deployment using /dev/tty, but both are required the moment a second AI agent can reach the host. The pipe design additionally eliminates the PTY access problem: ai-agent never needs tty group membership, and the operator sees full command context before responding to every confirmation request.

12 Exit Codes

aishell-gate-exec returns a precise exit code so the AI can distinguish between types of failure:

13 Conceptual Model

Traditional shells are designed to give a human direct, unmediated access to the operating system:

human  →  shell  →  operating system

AIShell-Gate inserts a deterministic policy gate between AI intent and OS execution:

AI  →  aishell-gate-exec  →  aishell-gate-policy  →  execve()  →  operating system

Instead of granting raw shell access, the system enforces policy, validates intent, and executes only what the policy engine has explicitly approved. The AI never touches a shell. The executor never makes a policy decision. The gate never bypasses itself.

Because each SSH connection is independent — connect, submit plan, disconnect — the system is stateless and predictable. There is no persistent channel for accumulated state or privilege to leak through.