Introduction

AI-SystemAssist is a lightweight HTTP server designed specifically for AI agents and LLMs. It allows agents to execute real shell commands on a machine and receive structured, machine-readable output.

Whether you're building autonomous agents, giving LLMs tool-use capabilities, or just want a simple way for scripts to run commands remotely, AI-SystemAssist provides a secure and easy-to-use interface.

Installation

TERMINAL

pip install AI-SystemAssist

Requires Python 3.11 or higher.

Quick Start

1. Start the server

ai-systemassist

The server will start on http://127.0.0.1:8765 and generate a token.

2. Send a command

curl -X POST -d 'whoami' \
  -H "X-Agent-Token: YOUR_TOKEN" \
  http://127.0.0.1:8765/execute

Starting the Server

Run the server using the installed CLI:

ai-systemassist

By default it binds to 127.0.0.1:8765 and generates a random auth token.

CLI Options

Flag	Description
--host	Host to bind to (default: 127.0.0.1)
--port, -p	Port to listen on (default: 8765)
--token	Auth token (generates one if omitted)
--allow-cors	Enable CORS headers (for local dev)

Environment Variables

AI_SYSTEMASSIST_TOKEN Auth token (recommended for production)

AI_SYSTEMASSIST_HOST Host interface

AI_SYSTEMASSIST_PORT Port number

Running as Admin

To execute commands with root/admin privileges, start the server with sudo:

sudo AI_SYSTEMASSIST_TOKEN="your-token" ai-systemassist

Authentication

Every request to /execute must include a token using one of these methods:

X-Agent-Token — Preferred header
Authorization: Bearer <token>
?token=<token> — Query param (use with caution)

Sending Commands

1. Raw Body (Simplest)

curl -X POST -d 'ls -la /tmp' \
  -H "X-Agent-Token: YOUR_TOKEN" \
  http://127.0.0.1:8765/execute

2. JSON Body (Recommended)

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-Agent-Token: YOUR_TOKEN" \
  -d '{"command": "apt update", "timeout": 60, "cwd": "/tmp"}' \
  http://127.0.0.1:8765/execute

3. Query Parameters

curl "http://127.0.0.1:8765/execute?token=YOUR_TOKEN&cmd=uptime"

Response Format

{
  "command": "the command that was executed",
  "success": true,
  "returncode": 0,
  "stdout": "standard output here\n",
  "stderr": "",
  "duration": 0.034
}

success — true if returncode == 0

returncode — Unix exit code

stdout / stderr — Output streams

duration — Time in seconds

Security Best Practices

Always use a strong, unique auth token
Default binding is localhost only — do not expose publicly without protection
Use sudo only when necessary
Consider running behind a reverse proxy with TLS
Never run on untrusted networks without additional controls

Agent Integration

AI-SystemAssist was designed to be used directly by LLM agents via simple HTTP calls. Agents can:

Explore the system with ls, df, ps
Run installation and configuration commands
Inspect logs and service status
Perform debugging and diagnostics

Troubleshooting

401 Unauthorized

Wrong or missing token. Check your X-Agent-Token header.

Connection refused

Server is not running or bound to wrong interface.

Permission denied

Start the server with sudo for root operations.