exec-guard - AI Agent Command Execution Module#

Safe and reliable system command execution for AI agents.

Quick Start#

CLI Mode#

bash

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

HTTP Service Mode#

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"}'

Core Capabilities#

CapabilityDescriptionSync ExecutionExecute command with timeout, wait for resultBackground ExecutionStart long tasks, get PID, query laterWatch WindowConfirm service startup before returning8KB Ring BufferHead-Tail dual buffer prevents OOMProcess ManagementQuery status, get logs, terminate processesMulti-Agent SharingHTTP service allows multiple agents to share state

API Reference#

POST /exec#

Execute a command:

json

{
  "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#

StatusMeaningsuccessCommand completed, exit code 0failedCommand failed, non-zero exittimeoutCommand killed after timeoutkilledProcess manually terminatedrunningBackground process active

Best Practices#

1. Set reasonable timeout - Prevent stuck commands
2. Use watch window for services - Confirm startup success
3. Use background mode for long tasks - Training, data processing
4. Clean up processes - Terminate when done

Full Documentation#

See references/AGENT_GUIDE.md for detailed usage guide and examples.

License#

MIT