Skip to content

Getting Started

Prerequisites

  • Python 3.11+ (recommended)
  • uv package manager (required)
  • Docker (for sandbox execution)
  • CodeQL (optional, for CodeQL analysis)

Installation

Step 1: Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

Step 2: Clone and Setup

# Clone the repository
git clone https://github.com/OpenSage-ADK/OpenSage.git
cd OpenSage

# Create virtual environment
uv venv --python "python3.11" ".venv"
source .venv/bin/activate

# Install dependencies
uv sync

# Install pre-commit hooks
uv run pre-commit install

Step 3: Additional Setup

CodeQL Setup (Optional): 

# Download CodeQL bundle
# Extract to: PROJECT_PATH/src/<package>/sandbox_scripts/codeql

Verify Installation

# Check OpenSage CLI is available
uv run opensage --help

Next Steps

Sandbox Images (Docker)

OpenSage uses Docker-based sandboxes. Some sandboxes require Python tooling inside their images (for initializers and Python-based helper scripts).

uv inside sandbox images

Sandbox Dockerfiles install uv using:

curl -LsSf https://astral.sh/uv/install.sh | sh

Python in sandbox images

For sandboxes that need Python, the Dockerfile creates a venv at /app/.venv:

uv venv --python 3.12

and installs Python dependencies into that venv:

uv pip install <package...>

Because sandbox command execution is non-persistent (each command is a fresh process), prefer calling the venv Python explicitly:

  • /app/.venv/bin/python ...
  • /app/.venv/bin/pip ...

Per-sandbox requirements (defaults)

  • main sandbox
  • Requires python3 and the Python package neo4j

  • Image built from src/<package>/templates/dockerfiles/main/Dockerfile

  • joern sandbox

  • Requires python3 and Python packages httpx + websockets
  • Image built from src/<package>/templates/dockerfiles/joern/Dockerfile

See Also