SudoDog Documentation

Overview

SudoDog is a free benchmark and monitoring platform for AI agents. Test your agents, get a score, compare on the leaderboard, and optionally upgrade to continuous monitoring.

            Two Ways to Use SudoDog:
            Benchmark (Free) - Run sudodog-benchmark to test your agent and get a score from 1-100 with recommendations
Dashboard (Free Beta) - Continuous monitoring, security alerts, cost tracking for teams

          

Quick Start

Installation

Install the SudoDog CLI from PyPI. Works on Linux, macOS, and Windows.

pip install sudodog

Run Your First Benchmark

Start your AI agent, then run the benchmark tool. It auto-detects running agents.

# Start your agent first (in another terminal) python your_agent.py # Then run the benchmark sudodog-benchmark

The benchmark will:

Scan for running AI agents on your machine
Let you select which agent to test
Monitor it for 30 seconds
Analyze with AI and give you a score
Provide recommendations and a shareable report link

Benchmark Tool

The benchmark tool tests your AI agent and provides a score from 1-100 with a letter grade (A+ to F).

What It Measures

+

CPU Usage

How efficiently your agent uses CPU resources

+

Memory Usage

Peak and average memory consumption

+

API Calls

Number and pattern of API calls made

+

Response Patterns

Consistency and quality of responses

+

Error Handling

How well your agent handles errors

+

Resource Efficiency

Overall resource utilization efficiency

What You Get

+

Score & Grade

1-100 score with letter grade (A+ to F)

+

Detailed Report

Shareable link with full analysis

+

Recommendations

AI-powered suggestions for improvement

+

Leaderboard

Compare against other agents

+

Badge

Embed in your GitHub README

Badge for Your README

After running a benchmark, you get a badge you can embed in your GitHub README:

[![SudoDog Score](https://sudodog.com/api/badge/YOUR_ID.svg)](https://sudodog.com/report/YOUR_ID)

sudodog-benchmark

The benchmark command tests and scores your AI agents.

Usage

sudodog-benchmark [OPTIONS]

Options

Option	Description
`--version`	Show version number
`--json`	Output results as JSON
`--no-submit`	Run locally without submitting to API
`--duration N`	Monitoring duration in seconds (default: 30)

Examples

# Interactive benchmark sudodog-benchmark # Output as JSON (for CI/CD) sudodog-benchmark --json # Run offline without submitting sudodog-benchmark --no-submit # Longer monitoring period sudodog-benchmark --duration 60

sudodog-scan

Scan your machine for running AI agents. Detects LangChain, AutoGPT, CrewAI, Claude Code, and custom agents.

Usage

sudodog-scan [OPTIONS]

Options

Option	Description
`--json`	Output as JSON
`--watch`	Continuously watch for new agents
`--interval N`	Watch interval in seconds (default: 5)
`--quiet`	Suppress non-essential output
`--api-key KEY`	API key for dashboard reporting

Examples

# One-time scan sudodog-scan # Watch mode - continuously detect new agents sudodog-scan --watch # Report to dashboard sudodog-scan --api-key YOUR_API_KEY

sudodog run

Run an agent with continuous monitoring. Connects to the dashboard for real-time visibility.

Usage

sudodog run [OPTIONS] COMMAND [ARGS...]

Options

Option	Description
`--name NAME`	Display name for the agent in dashboard
`--agent-id ID`	Custom agent identifier
`--docker`	Run inside a Docker container
`--cpu-limit N`	CPU limit (e.g., 1.0 = 1 core)
`--memory-limit N`	Memory limit (e.g., 512m, 1g)
`--no-network`	Disable network access
`--guardrails POLICY`	Apply guardrail policy

Examples

# Basic usage sudodog run python agent.py # With a name sudodog run --name "Production Agent" python agent.py # With resource limits sudodog run --cpu-limit 2.0 --memory-limit 1g python agent.py # With guardrails sudodog run --guardrails production-policy python agent.py

Connecting to Dashboard

To see your agent in the dashboard, first initialize with your API key:

# Initialize with API key sudodog init # Then run your agent sudodog run python agent.py

sudodog integrate

Integrate SudoDog with other tools like Claude Code or Docker.

Claude Code Integration

Add SudoDog as a hook to Claude Code for automatic monitoring:

sudodog integrate claude-code

This adds SudoDog hooks to your Claude Code configuration, enabling observability without changing your workflow.

Docker Integration

Get configuration for Docker-based agent monitoring:

sudodog integrate docker

This outputs MCP configuration for adding SudoDog to your Docker setup.

sudodog config

View and modify SudoDog configuration.

Usage

sudodog config [OPTIONS]

Options

Option	Description
`--show`	Show current configuration
`--set KEY=VALUE`	Set a configuration value

Examples

# Show current config sudodog config --show # Set API key sudodog config --set api_key=YOUR_API_KEY # Set custom endpoint sudodog config --set endpoint=https://api.sudodog.com

Adding Agents to Dashboard

There are two ways to add agents to the SudoDog dashboard for continuous monitoring.

Method 1: Auto-Detection (Recommended)

The dashboard can detect agents running on machines where you've installed the CLI:

Install the CLI: pip install sudodog
Run the scanner with your API key: sudodog-scan --api-key YOUR_KEY
Go to "Add Agent" in the dashboard
Click "Add to Dashboard" on any detected agent

Method 2: Manual Setup

Run agents with the sudodog run command:

# Initialize (one time) sudodog init # Run your agent sudodog run python your_agent.py

Getting Your API Key

1. Log in to the dashboard at dashboard.sudodog.com
2. Go to "Add Agent" page
3. Click "Create API Key"
4. Copy and store your key securely

Mission Control

Mission Control is the central monitoring hub for all your AI agents. It displays real-time metrics including:

+

Active Agents

Total number of running AI agents

+

Daily Spending

Real-time cost tracking across all providers

+

Security Alerts

Active security incidents requiring attention

+

Health Score

Overall system health indicator (0-100)

Security Center

Monitor and protect your AI agents from security threats. The Security Center detects:

+

Prompt Injection

Malicious prompts attempting to manipulate agent behavior

+

Data Exfiltration

Unauthorized data transfer attempts

+

Unauthorized Access

Access attempts from unknown sources

+

Anomalous Behavior

Unusual patterns that deviate from normal operation

Cost Intelligence

Track and optimize your AI spending across all providers and models.

+

Per-Agent Breakdown

See exactly how much each agent costs

+

Provider Analytics

Compare costs across OpenAI, Anthropic, AWS, etc.

+

Budget Alerts

Get notified when approaching limits

+

Optimization Tips

AI-powered recommendations to reduce costs

Guardrails

Guardrails let you define security policies that block dangerous operations before they execute.

Key Features

+

File Access Rules

Block access to sensitive files and directories

+

Network Restrictions

Prevent connections to unauthorized domains

+

Command Blocking

Stop dangerous shell commands before execution

+

Output Filtering

Redact PII and secrets from agent output

CLI Usage

# Run agent with guardrails sudodog run --guardrails production-policy python agent.py # List available policies sudodog guardrails list

API Reference

Benchmark API (Public)

Method	Endpoint	Description
POST	`/api/v1/benchmark`	Submit benchmark results
GET	`/api/v1/benchmark/{id}`	Get benchmark report
GET	`/api/v1/benchmark/leaderboard`	Get public leaderboard
GET	`/api/v1/benchmark/frameworks`	Get framework statistics
GET	`/api/v1/badge/{id}.svg`	Get badge image

Dashboard API (Authenticated)

Method	Endpoint	Description
GET	`/api/v1/agents`	List all agents
POST	`/api/v1/telemetry`	Submit telemetry data
GET	`/api/v1/costs/summary`	Get cost summary
GET	`/api/v1/security/events`	List security events
GET	`/api/v1/guardrails/policies`	List guardrail policies
GET	`/api/v1/agents/shadow/list`	List detected shadow agents
POST	`/api/v1/agents/shadow/{id}/wrap`	Add shadow agent to dashboard

Supported Frameworks

SudoDog works with any AI agent framework. Here are some we automatically detect:

LangChain

AutoGPT

CrewAI

Claude Code

OpenAI GPT

Anthropic Claude

AWS Bedrock

Azure OpenAI

Google Vertex AI

Hugging Face

LlamaIndex

Custom Agents

System Requirements

CLI

Python 3.8+
pip package manager
Linux, macOS, or Windows

Dashboard

Modern web browser
Chrome 90+
Firefox 88+
Safari 14+

Self-Hosted

Docker 20+
PostgreSQL 13+
4GB RAM minimum

Support

Need help? We're here for you.

Email: support@sudodog.com
GitHub: github.com/SudoDog-official/sudodog