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