# AgentControl

> Source: <https://github.com/kyzrxe-max/agent-guard>
> Published: 2026-07-27 06:26:40+00:00

**Open-source runtime control plane for AI coding agents**

**Think "cloud firewall for AI agents."** AgentControl sits between your agent and its tools — intercepting every tool call, enforcing policy, requiring human approval for risky operations, and logging everything.

```
┌─────────────────────────────────────────────────────────┐
│ AgentControl Dashboard                                   │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Agents  │  ON  │  Name       │  Risk  │  Actions   │ │
│ ├─────────────────────────────────────────────────────┤ │
│ │ ◉ ON   │  repo-mnt  │  Repo Bot  │  HIGH  │ [⏸] [🗑] │ │
│ │ ◯ OFF  │  safe-bot  │  Safe Bot  │  LOW   │ [▶] [🗑] │ │
│ └─────────────────────────────────────────────────────┘ │
│ Policy: block rm -rf, require_approval for PR merges     │
│ Audit: 47 tool calls logged, 12 blocked, 3 approvals     │
└─────────────────────────────────────────────────────────┘
```

Record a live demo:`npm install -g terminalizer && terminalizer record demo`

```
npm install
cp .env.example .env
npm run dev
```

Open ** http://localhost:8080** — the dashboard is live. That's it.

| Problem | Solution |
|---|---|
Agent runs `rm -rf /` |
Blocked by dangerous-command guardrails |
| Agent wants to merge a PR | Requires human approval in the dashboard |
Agent accesses `.env` secrets |
Blocked by path-traversal guardrails |
| You need an audit trail | Every tool call logged with decision, approval, and result |
| Multiple agents, different trust levels | Risk-level enforcement: low auto-allows, high requires approval, critical blocks all |
| You want to pause an agent | Toggle on/off from dashboard or CLI |

**Policy Engine**— YAML-defined rules that decide`allow`

,`block`

, or`require_approval`

per tool call**Agent Registry**— Register agents with identities, allowed tools, and risk levels** Human-in-the-Loop**— Approve or deny risky tool calls from the dashboard or API** Audit Timeline**— Complete replay of every tool call, decision, and approval** Dashboard UI**— Single-page HTML app: monitor agents, approve calls, view audit logs** CLI**— Full command-line interface for scripting and automation** API Key Management**— Create and revoke scoped API keys via the dashboard or CLI** Risk Levels**—`low`

/`medium`

/`high`

/`critical`

— each enforces different policies**Enable/Disable Agents**— Stop or start agents without deleting them** Docker**— One-command deploy with`docker compose up -d`

**Self-Hosted**— Your data stays on your infrastructure. No cloud dependency.

```
┌──────────┐     ┌──────────────────────────────────────────┐     ┌──────────┐
│  Agent   │────▶│            AgentControl Gateway           │────▶│  Tools   │
│ (LLM)    │     │                                          │     │ (shell,  │
└──────────┘     │  ┌──────────┐  ┌──────────┐  ┌────────┐ │     │  files,  │
                 │  │  Policy  │──│ Approval │──│  Audit │ │     │  github) │
                 │  │  Engine  │  │   Queue  │  │  Log   │ │     └──────────┘
                 │  └──────────┘  └──────────┘  └────────┘ │
                 │       │              │              │     │
                 │       ▼              ▼              ▼     │
                 │  ┌──────────────────────────────────────┐ │
                 │  │            Agent Registry             │ │
                 │  │  (SQLite: agents, policies, runs)     │ │
                 │  └──────────────────────────────────────┘ │
                 └──────────────────────────────────────────┘
```

Every tool call passes through the gateway:

**Policy Engine** evaluates the call against YAML rules and risk level**Approval Queue** holds calls that need human review**Audit Log** records the full decision + execution trace

```
# Register an agent
npm run cli -- agent register \
  --id repo-maintainer \
  --name "Repo Maintainer" \
  --owner engineering \
  --environment development \
  --purpose "Safely maintain repository tasks" \
  --tools shell.run,filesystem.read,filesystem.write,github.mock_merge_pr \
  --risk medium

# Try allowed commands
npm run cli -- tools call --agent repo-maintainer --tool shell.run --input '{"command":"npm test"}'

# Dangerous commands are always blocked
npm run cli -- tools call --agent repo-maintainer --tool shell.run --input '{"command":"rm -rf /"}'

# High-risk tools need approval
npm run cli -- tools call --agent repo-maintainer --tool github.mock_merge_pr --input '{"repo":"company/api","pr":42}'

# Approve from CLI
npm run cli -- approvals list
npm run cli -- approvals approve <id> --by secops-admin --reason "Verified"

# Stop/start agents
npm run cli -- agent toggle --id repo-maintainer --disable
npm run cli -- agent toggle --id repo-maintainer --enable

# View audit replay
npm run cli -- runs replay <run-id>

# Delete agent
npm run cli -- agent delete --id repo-maintainer

# Manage API keys
npm run cli -- keys create --name "My Key"
npm run cli -- keys list
npm run cli -- keys delete <key-id>
```

Windows PowerShell:Replace single quotes with escaped double quotes:

`--input "{""command"":""npm test""}"`

All endpoints require `x-api-key`

header or `Authorization: Bearer <key>`

.

| Method | Path | Description |
|---|---|---|
`GET` |
`/health` |
Health check |
`GET` |
`/v1/stats` |
Dashboard metrics |
`POST` |
`/v1/agents` |
Register an agent |
`GET` |
`/v1/agents` |
List agents |
`GET` |
`/v1/agents/:id` |
Get agent details |
`PATCH` |
`/v1/agents/:id` |
Enable/disable agent |
`DELETE` |
`/v1/agents/:id` |
Delete an agent |
`POST` |
`/v1/tools/call` |
Execute or evaluate a tool call |
`GET` |
`/v1/approvals` |
List approval requests |
`POST` |
`/v1/approvals/:id/approve` |
Approve a pending call |
`POST` |
`/v1/approvals/:id/deny` |
Deny a pending call |
`GET` |
`/v1/runs` |
List audit runs |
`GET` |
`/v1/runs/:id` |
Run replay timeline |
`GET` |
`/v1/policies` |
View active policy |
`POST` |
`/v1/policies/reload` |
Reload policy from disk |
`POST` |
`/v1/api-keys` |
Create API key |
`GET` |
`/v1/api-keys` |
List API keys |
`DELETE` |
`/v1/api-keys/:id` |
Delete API key |

```
export API_KEY=your-secure-key
docker compose up -d
# Open http://localhost:8080
npm test
```

Runs 18 tests across core engine, HTTP API, and CLI end-to-end flow.

| Feature | AgentControl | Portkey | Guardrails AI |
|---|---|---|---|
| Open source | ✅ MIT | ❌ | ✅ Apache 2.0 |
| Self-hosted | ✅ | ❌ | ✅ |
| Human-in-the-loop | ✅ Native | ❌ | Partial |
| Audit timeline | ✅ Full replay | ✅ | ❌ |
| Risk levels | ✅ 4-tier | ❌ | ✅ |
| Dashboard | ✅ Built-in | ✅ | ❌ |
| API key management | ✅ | ✅ | ❌ |
| CLI | ✅ | ✅ | ❌ |
| Install time | <30s | SaaS | 5min |

| Framework | Guide |
|---|---|
| OpenAI SDK |
|

[examples/langchain.md](/kyzrxe-max/agent-guard/blob/main/examples/langchain.md)[examples/crewai.md](/kyzrxe-max/agent-guard/blob/main/examples/crewai.md)Copy `.env.example`

to `.env`

and set your `API_KEY`

. See `.env`

for all available options.

PRs welcome! Check [open issues](https://github.com/kyzrxe-max/agent-guard/issues) for community-requested features.

MIT