Getting Started

Installation

AgentCop works as a CLI tool, Python library, and REST API. Install what fits your workflow.

PyPI (recommended)

The easiest way to get started. Installs the agentcop CLI and the Python library in a single command.

terminal
$ pip install agentcop
Successfully installed agentcop-1.0.0
 
$ agentcop --version
agentcop 1.0.0

We recommend installing inside a virtual environment to avoid dependency conflicts:

terminal
$ python -m venv .venv && source .venv/bin/activate
$ pip install agentcop

From source

Install from the GitHub repository to get the latest unreleased changes or to contribute to development.

terminal
$ git clone https://github.com/agentcop/agentcop
$ cd agentcop
$ pip install -e ".[dev]"

The [dev] extra includes testing dependencies (pytest, httpx, ruff). Omit it for a lighter install if you are not contributing.

Docker

Use the official image to scan files without installing Python locally. Mount your project directory into the container at /workspace.

terminal
$ docker pull ghcr.io/agentcop/agentcop:latest
$ docker run -v $(pwd):/workspace agentcop scan /workspace/agent.py

Pass environment variables with -e flags, for example -e ANTHROPIC_API_KEY=sk-ant-... to enable AI-enhanced analysis.

Self-hosted API server

Run the AgentCop REST API on your own infrastructure — useful for air-gapped environments, team-wide scanning endpoints, or CI pipelines that need low-latency local access.

Direct with uvicorn

terminal
$ git clone https://github.com/agentcop/agentcop
$ cd agentcop
$ pip install -r requirements.txt
$ uvicorn main:app --host 0.0.0.0 --port 8000
INFO: Started server process [12345]
INFO: Uvicorn running on http://0.0.0.0:8000

With Docker Compose

terminal
$ docker-compose up -d
# API available at http://localhost:8000

System requirements

Component Minimum Recommended
Python 3.9 3.11+
RAM 512 MB 2 GB
Disk 200 MB 500 MB
OS Linux / macOS / Windows Linux

Dependencies

AgentCop's key runtime dependencies are listed below. All are pinned in requirements.txt and installed automatically via pip.

Package Purpose
fastapi REST API framework for the scan server
uvicorn ASGI server that runs FastAPI
anthropic Claude SDK — powers AI-enhanced scan explanations
tree-sitter Incremental AST parser for precise code analysis
httpx Async HTTP client used in tests and API examples
sqlalchemy ORM layer for scan result caching (SQLite by default)

Environment variables

Configure AgentCop via environment variables — set them in your shell, .env file, or CI secrets store.

bash 
ANTHROPIC_API_KEY=sk-ant-...   # Required for AI-enhanced scan
DATABASE_URL=sqlite:///./agentcop.db  # Default: SQLite
PORT=8000                       # API server port
AGENTCOP_LOG_LEVEL=INFO        # Logging verbosity
ℹ
ANTHROPIC_API_KEY is optional. Without it, AgentCop uses rule-based detection only. With it, you get AI-enhanced analysis and natural language explanations for every finding — including suggested code fixes tailored to your specific agent pattern.
Variable Default Description
ANTHROPIC_API_KEY — Enables AI-enhanced scan mode via Claude
DATABASE_URL sqlite:///./agentcop.db SQLAlchemy connection string for scan cache
PORT 8000 Port the API server listens on
AGENTCOP_LOG_LEVEL INFO Log verbosity: DEBUG, INFO, WARNING, ERROR

Verification

Confirm your installation is working correctly with the health command:

terminal
$ agentcop --version
agentcop 1.0.0
 
$ agentcop health
✓ Scanner engine: OK
✓ API connection: OK
✓ Database: OK

If any check fails, see the Quickstart troubleshooting section or open an issue on GitHub.