概述

exec-guard - AI Agent Command Execution Module

Safe and reliable system command execution for AI agents.

Quick Start

CLI Mode

echo '{"command": "ls -la"}' | node scripts/dist/index.js

HTTP Service Mode

node scripts/dist/index.js --server --port 8080
curl -X POST http://localhost:8080/exec -H "Content-Type: application/json" -d '{"command": "ls -la"}'

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:

{
  "command": "required - system command",
  "workingDir": "optional - working directory",
  "timeoutSeconds": "optional - default 30",
  "runInBackground": "optional - default false",
  "watchDurationSeconds": "optional - for service startup",
  "env": "optional - custom environment variables"
}

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
--------	---------
`success`	Command completed, exit code 0
`failed`	Command failed, non-zero exit
`timeout`	Command killed after timeout
`killed`	Process manually terminated
`running`	Background process active

Best Practices

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

版本历史

共 1 个版本

v1.0.6 当前

2026-05-03 03:32 安全安全

安全检测

腾讯云安全 (Keen)

安全，无风险

查看报告

腾讯云安全 (Sanbu)