exec-guard - AI Agent Command Execution Module
Safe and reliable system command execution for AI agents.
Quick Start
CLI Mode
CODEBLOCK0
HTTP Service Mode
CODEBLOCK1
Core Capabilities
| Capability | Description |
|---|
| Sync Execution | Execute command with timeout, wait for result |
| Background Execution |
Start long tasks, get PID, query later |
|
Watch Window | Confirm service startup before returning |
|
8KB Ring Buffer | Head-Tail dual buffer prevents OOM |
|
Process Management | Query status, get logs, terminate processes |
|
Multi-Agent Sharing | HTTP service allows multiple agents to share state |
API Reference
POST /exec
Execute a command:
CODEBLOCK2
GET /process/:pid
Query process status.
GET /process/:pid/logs
Get process output logs.
DELETE /process/:pid
Terminate a process.
GET /processes
List all background processes.
Response Status
| Status | Meaning |
|---|
| INLINECODE0 | Command completed, exit code 0 |
| INLINECODE1 |
Command failed, non-zero exit |
|
timeout | Command killed after timeout |
|
killed | Process manually terminated |
|
running | Background process active |
Best Practices
- 1. Set reasonable timeout - Prevent stuck commands
- Use watch window for services - Confirm startup success
- Use background mode for long tasks - Training, data processing
- Clean up processes - Terminate when done
Full Documentation
See references/AGENT_GUIDE.md for detailed usage guide and examples.
License
MIT
exec-guard - AI智能体命令执行模块
为AI智能体提供安全可靠的系统命令执行功能。
快速开始
命令行模式
bash
echo {command: ls -la} | node scripts/dist/index.js
HTTP服务模式
bash
node scripts/dist/index.js --server --port 8080
curl -X POST http://localhost:8080/exec -H Content-Type: application/json -d {command: ls -la}
核心能力
| 能力 | 描述 |
|---|
| 同步执行 | 带超时执行命令,等待结果返回 |
| 后台执行 |
启动长时间任务,获取进程ID,后续查询 |
|
等待窗口 | 返回前确认服务已启动 |
|
8KB环形缓冲区 | 头尾双缓冲区防止内存溢出 |
|
进程管理 | 查询状态、获取日志、终止进程 |
|
多智能体共享 | HTTP服务允许多个智能体共享状态 |
API参考
POST /exec
执行命令:
json
{
command: 必填 - 系统命令,
workingDir: 可选 - 工作目录,
timeoutSeconds: 可选 - 默认30秒,
runInBackground: 可选 - 默认false,
watchDurationSeconds: 可选 - 用于服务启动,
env: 可选 - 自定义环境变量
}
GET /process/:pid
查询进程状态。
GET /process/:pid/logs
获取进程输出日志。
DELETE /process/:pid
终止进程。
GET /processes
列出所有后台进程。
响应状态
| 状态 | 含义 |
|---|
| success | 命令执行成功,退出码0 |
| failed |
命令执行失败,非零退出码 |
| timeout | 命令超时被终止 |
| killed | 进程被手动终止 |
| running | 后台进程正在运行 |
最佳实践
- 1. 设置合理超时 - 防止命令卡死
- 服务使用等待窗口 - 确认启动成功
- 长时间任务使用后台模式 - 训练、数据处理等
- 清理进程 - 完成后及时终止
完整文档
详细使用指南和示例请参见 references/AGENT_GUIDE.md。
许可证
MIT