Skip to main content
This guide walks you through setting up a complete development environment for contributing to Esprit CLI.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Python 3.12+ (supports 3.12, 3.13, 3.14)
  • Docker (running) - Required for the pentest sandbox
  • Poetry - Python dependency management
  • Git - Version control
Check your Python version with python --version. Esprit requires Python 3.12 or higher.

​
Installation Steps

1

Clone the repository

Clone the Esprit repository from GitHub:
git clone https://github.com/esprit-cli/Esprit.git
cd Esprit
2

Install development dependencies

The easiest way to set up your development environment is using the Makefile:
make setup-dev
This command will:
  • Install all development dependencies via Poetry
  • Set up pre-commit hooks automatically
  • Verify your environment is ready
If you prefer to install manually:
# Install all dependencies including dev tools
poetry install --with=dev

# Set up pre-commit hooks
poetry run pre-commit install
3

Configure your LLM provider

Esprit requires an LLM provider for AI-powered testing. Set up your preferred provider:
# Option 1: Use environment variables
export ESPRIT_LLM="anthropic/claude-sonnet-4-5-20250514"
export LLM_API_KEY="sk-ant-..."

# Option 2: Use OAuth login
poetry run esprit provider login anthropic
poetry run esprit provider login openai
poetry run esprit provider login google
For free tier access without API keys, use Antigravity:
poetry run esprit provider login antigravity
4

Verify installation

Run a test scan to verify everything is working:
poetry run esprit scan https://example.com --non-interactive
You can also run the quality checks to ensure your environment is properly configured:
make check-all

​
Development Tools

Esprit uses a comprehensive suite of development tools configured in pyproject.toml:

​
Code Formatting

  • Ruff (primary formatter) - Fast Python linter and formatter
  • Black - Opinionated code formatter (100-character line length)
  • isort - Import statement organizer

​
Type Checking

  • mypy - Static type checker with strict mode enabled
  • pyright - Alternative type checker from Microsoft
Configuration highlights:
  • Strict type checking enabled
  • Python 3.12 target version
  • Comprehensive type checking rules

​
Linting

  • Ruff - Primary linter with 30+ rule sets enabled
  • Pylint - Additional Python code analysis
  • Bandit - Security-focused linting
Ruff rules include:
  • pycodestyle (E, W)
  • Pyflakes (F)
  • isort (I)
  • flake8 plugins (security, bugbear, comprehensions, etc.)
  • Pylint (PL)
  • Security checks (S)

​
Testing

  • pytest - Test framework with async support
  • pytest-asyncio - Async test support
  • pytest-cov - Code coverage reporting
  • pytest-mock - Mocking utilities

​
Project Structure

Esprit/
├── esprit/                 # Main package
│   ├── agents/            # AI agent implementations
│   ├── config/            # Configuration management
│   ├── gui/               # GUI dashboard (optional)
│   ├── interface/         # CLI interface
│   ├── skills/            # Agent knowledge packages
│   ├── tools/             # Agent tools (browser, terminal, etc.)
│   └── telemetry/         # Usage tracking
├── tests/                 # Test suite
│   ├── agents/
│   ├── config/
│   ├── gui/
│   └── interface/
├── docs/                  # Documentation
├── containers/            # Docker configurations
├── pyproject.toml         # Project configuration & dependencies
├── Makefile               # Development commands
└── CONTRIBUTING.md        # Contribution guidelines

​
Quick Start Commands

# Run Esprit in development mode
poetry run esprit --target https://example.com

# Run with specific scan mode
poetry run esprit scan https://example.com -m quick
poetry run esprit scan https://example.com -m standard
poetry run esprit scan https://example.com -m deep

# Scan local codebase
poetry run esprit scan ./my-project

# Scan GitHub repository
poetry run esprit scan https://github.com/user/repo

​
Optional Dependencies

Esprit supports several optional feature sets:

​
Vertex AI (Google Cloud)

poetry install --extras vertex

​
Sandbox Tools (for Docker sandbox)

poetry install --extras sandbox
Includes: FastAPI, Uvicorn, IPython, Playwright, and more.

​
GUI Dashboard

poetry install --extras gui
Includes: FastAPI, Uvicorn, WebSockets for the web dashboard.

​
Environment Variables

Key environment variables for development:
VariableRequiredDescription
ESPRIT_LLMNoLLM model identifier (e.g., anthropic/claude-sonnet-4-5)
LLM_API_KEYNo*API key for direct LLM access
LLM_API_BASENoCustom API endpoint (for Ollama, etc.)
ESPRIT_IMAGENoCustom Docker sandbox image
PERPLEXITY_API_KEYNoEnables web search during scans
*Not required when using OAuth providers or Esprit Cloud

​
Troubleshooting

​
Docker Issues

If you encounter Docker-related errors: 
# Verify Docker is running
docker ps

# Pull the latest sandbox image
docker pull esprit/sandbox:latest

​
Poetry Issues

If Poetry installation fails: 
# Clear Poetry cache
poetry cache clear pypi --all

# Reinstall dependencies
poetry install --with=dev --no-cache

​
Type Checking Errors

If you see type checking errors during development: 
# Run type checkers individually
poetry run mypy esprit/
poetry run pyright esprit/

​
Next Steps

Running Tests

Learn how to run and write tests

Contributing

Read the contribution guidelines

Build docs developers (and LLMs) love

Get started for freeTalk to us