Installation

System Requirements

Before installing Esprit, ensure you have:

Python 3.12+

Required for running the Esprit agent runtime

Docker (Optional)

Only needed for local mode with your own LLM provider. Not required for Esprit Cloud.

Using Esprit Cloud? You can skip Docker installation entirely. Esprit Cloud runs scans in managed sandboxes.

Installation Methods

Choose the installation method that best fits your workflow:

curl (Recommended)
Homebrew (macOS)
npm (Node.js)
pip (Python)
From Source

The curl installer automatically detects your system and installs all dependencies:

curl -fsSL https://raw.githubusercontent.com/esprit-cli/Esprit/main/scripts/install.sh | bash

What does the installer do?

The installation script:

Checks for Python 3.12+ and git
Clones the Esprit runtime repository to ~/.esprit/runtime
Creates a Python virtual environment at ~/.esprit/venv
Installs Esprit and dependencies via pip
Creates a launcher script at ~/.esprit/bin/esprit
Adds ~/.esprit/bin to your shell PATH
Pre-pulls the Docker sandbox image (optional)

Installation takes 2-5 minutes depending on your connection speed.

Custom installation location

Override the default install location with ESPRIT_HOME:

export ESPRIT_HOME=/opt/esprit
curl -fsSL https://raw.githubusercontent.com/esprit-cli/Esprit/main/scripts/install.sh | bash

Skip Docker image pull

If you’re using Esprit Cloud exclusively, skip the Docker image warm-up:

export ESPRIT_SKIP_DOCKER_WARM=1
curl -fsSL https://raw.githubusercontent.com/esprit-cli/Esprit/main/scripts/install.sh | bash

Activate Your Installation

After installation, either restart your terminal or run:

export PATH="$HOME/.esprit/bin:$PATH"

Verify the installation:

esprit --version

You should see output like esprit 0.7.22

Install via Homebrew for easy updates and dependency management:

brew tap improdead/esprit
brew install esprit

Update to Latest Version

brew update
brew upgrade esprit

Verify Installation

esprit --version
which esprit
# /opt/homebrew/bin/esprit (Apple Silicon)
# /usr/local/bin/esprit (Intel)

Homebrew automatically manages Python dependencies and PATH configuration.

Install globally via npm if you prefer the Node.js ecosystem:

npm install -g esprit-cli@latest

Requires Node.js 18 or higher. The npm package is a wrapper that downloads the Python runtime on first run.

Update to Latest Version

npm update -g esprit-cli

Verify Installation

esprit --version

The npm package handles platform detection automatically (macOS, Linux, Windows WSL).

Install directly via pip into your Python environment:

pip install esprit-cli

Or with pipx for isolated installation:

pipx install esprit-cli

Update to Latest Version

pip install --upgrade esprit-cli
# or
pipx upgrade esprit-cli

Verify Installation

esprit --version
python -m esprit --version

Make sure you’re using Python 3.12 or higher:

python --version
# Python 3.12.0 or higher

For development or running the latest unreleased changes:

Clone the Repository

git clone https://github.com/esprit-cli/Esprit.git
cd Esprit

Install Poetry

Esprit uses Poetry for dependency management:

pip install poetry

Or use the official installer:

curl -sSL https://install.python-poetry.org | python3 -

Install Dependencies

poetry install

This creates a virtual environment and installs all runtime and development dependencies.

Run Esprit

poetry run esprit --version
poetry run esprit scan https://example.com

Development Commands

poetry run pytest
poetry run pytest --cov=esprit

See pyproject.toml for the complete list of development tools and configuration.

Docker Setup (Local Mode Only)

If you plan to use local mode with your own LLM provider (instead of Esprit Cloud), you need Docker:

Install Docker

Download Docker Desktop from docker.comOr on Linux, install Docker Engine:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

After adding yourself to the docker group, log out and back in for changes to take effect.

Verify Docker is Running

docker info

You should see output showing Docker is running. If not, start Docker Desktop or:

sudo systemctl start docker

Pre-Pull the Sandbox Image (Optional)

Download the Esprit sandbox image to speed up your first scan:

docker pull improdead/esprit-sandbox:latest

The image is ~2GB and contains all security testing tools.

Apple Silicon (M1/M2/M3)? The sandbox image uses linux/amd64 emulation on ARM Macs. Performance is excellent thanks to Rosetta 2.

Platform-Specific Notes

Alpine Linux / musl libc

If you’re running Alpine or another musl-based distribution, install build tools before running the installer:

apk add --no-cache build-base linux-headers rust cargo python3-dev

Some Python dependencies (like cryptography) compile from source on musl systems.

Windows (WSL2)

Esprit runs on Windows via WSL2:

Install WSL2
Install Ubuntu or Debian from the Microsoft Store
Inside WSL, follow the curl installation instructions
Install Docker Desktop for Windows with WSL2 backend

Esprit Cloud works on WSL2 without Docker.

Corporate Proxy / Firewall

If you’re behind a corporate proxy, configure environment variables:

export HTTP_PROXY=http://proxy.corp.com:8080
export HTTPS_PROXY=http://proxy.corp.com:8080
export NO_PROXY=localhost,127.0.0.1

For Docker:

mkdir -p ~/.docker
cat > ~/.docker/config.json <<EOF
{
  "proxies": {
    "default": {
      "httpProxy": "http://proxy.corp.com:8080",
      "httpsProxy": "http://proxy.corp.com:8080",
      "noProxy": "localhost,127.0.0.1"
    }
  }
}
EOF

Air-Gapped / Offline Installation

For offline environments:

Download the repository as a tarball on a machine with internet
Transfer to the air-gapped system
Extract and install:

tar -xzf Esprit-main.tar.gz
cd Esprit-main
pip install poetry
poetry install --no-interaction

You’ll also need to manually transfer the Docker sandbox image:

# On internet-connected machine:
docker pull improdead/esprit-sandbox:latest
docker save improdead/esprit-sandbox:latest | gzip > esprit-sandbox.tar.gz

# On air-gapped machine:
docker load < esprit-sandbox.tar.gz

Troubleshooting

Command not found: esprit

The installation path isn’t in your shell’s PATH. Add it manually:

echo 'export PATH="$HOME/.esprit/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Python version too old

Esprit requires Python 3.12+. Install a newer version:

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.12 python3.12-venv

Then re-run the installer.

Docker permission denied

If you see permission denied while trying to connect to the Docker daemon:

sudo usermod -aG docker $USER
newgrp docker

Or on macOS, ensure Docker Desktop is running.

Installation fails on ARM/Apple Silicon

If dependency compilation fails on M1/M2/M3 Macs:

# Install Rosetta 2 if not already installed
softwareupdate --install-rosetta

# Install Homebrew dependencies
brew install rust openssl

# Retry installation
curl -fsSL https://raw.githubusercontent.com/esprit-cli/Esprit/main/scripts/install.sh | bash

Updating Esprit

To update to the latest version:

esprit --self-update

The --self-update flag automatically downloads and installs the latest version of Esprit.

Uninstalling

To completely remove Esprit:

rm -rf ~/.esprit
# Remove PATH export from your shell config file

Scan results in esprit_runs/ are preserved during uninstallation. Delete manually if needed.

Next Steps

Quick Start

Now that Esprit is installed, run your first security scan

Get Started

Configuration

Usage

Architecture

Vulnerability Detection

System Requirements

Python 3.12+

Docker (Optional)

Installation Methods

Activate Your Installation

Update to Latest Version

Verify Installation

Update to Latest Version

Verify Installation

Update to Latest Version

Verify Installation

Development Commands

Docker Setup (Local Mode Only)

Platform-Specific Notes

Troubleshooting

Updating Esprit

Uninstalling

Next Steps

Quick Start

Build docs developers (and LLMs) love

Get Started

Configuration

Usage

Architecture

Vulnerability Detection

​System Requirements

Python 3.12+

Docker (Optional)

​Installation Methods

​Activate Your Installation

​Update to Latest Version

​Verify Installation

​Update to Latest Version

​Verify Installation

​Update to Latest Version

​Verify Installation

​Development Commands

​Docker Setup (Local Mode Only)

​Platform-Specific Notes

​Troubleshooting

​Updating Esprit

​Uninstalling

​Next Steps

Quick Start

Build docs developers (and LLMs) love

System Requirements

Installation Methods

Activate Your Installation

Update to Latest Version

Verify Installation

Update to Latest Version

Verify Installation

Update to Latest Version

Verify Installation

Development Commands

Docker Setup (Local Mode Only)

Platform-Specific Notes

Troubleshooting

Updating Esprit

Uninstalling

Next Steps