# How to Run SkillSpector Using Docker: Complete Setup Guide

> Easily run SkillSpector security scans with Docker. Mount your code and invoke the CLI for dependency-free analysis. Get the complete setup guide for NVIDIA/SkillSpector.

- Repository: [NVIDIA Corporation/SkillSpector](https://github.com/NVIDIA/SkillSpector)
- Tags: how-to-guide
- Published: 2026-06-16

---

**SkillSpector ships a minimal multi-stage Docker image that lets you run security scans without installing Python dependencies locally by mounting your code to `/scan` and invoking the `skillspector` CLI as the container entrypoint.**

NVIDIA/SkillSpector is an AI security scanner designed to analyze skill bundles for vulnerabilities. If you need to run SkillSpector using Docker to avoid Python environment management, the repository provides a production-ready container built via an optimized multi-stage Dockerfile.

## Understanding the SkillSpector Docker Architecture

The containerization strategy defined in the repository root `Dockerfile` uses a multi-stage build to minimize image size and eliminate build dependencies from the final runtime.

### Builder Stage

The first stage uses `python:3.12-slim-bookworm` as the base image. According to lines 1-8 of the Dockerfile, this stage copies the project source, creates a virtual environment, and installs the package with `pip install --no-cache-dir .` to ensure a clean, cache-free installation.

### Runtime Stage

The second stage copies the pre-built virtual environment from the builder, sets `PATH="/app/.venv/bin:$PATH"` so the `skillspector` command is available system-wide, and establishes `/scan` as the working directory (lines 9-15). This design ensures the runtime image contains only the necessary binaries without build tools.

### Entrypoint Configuration

The container declares `skillspector` as its entrypoint in lines 16-17 of the Dockerfile. This entrypoint invokes the CLI implementation found in [`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py), meaning any arguments you append to `docker run` are forwarded directly to the SkillSpector command.

## Building the Docker Image

You can build the image manually or use the convenience target in the provided Makefile.

```bash

# Build manually with a specific tag

docker build -t skillspector .

# Or use the Makefile shortcut

make docker-build

```

## Running SkillSpector Scans in Docker

To analyze skills, mount a host directory to the container's `/scan` path and specify the target path relative to that mount point.

### Static Analysis Without LLM

For air-gapped environments or quick static checks, disable LLM analysis using the `--no-llm` flag:

```bash
docker run --rm -v "$PWD:/scan" skillspector scan ./my-skill/ --no-llm

```

### LLM-Enabled Scans Using Environment Files

For enhanced analysis requiring LLM capabilities, create an `.env` file and mount it via `--env-file`:

```bash

# Create environment file

cat > .env <<'EOF'
SKILLSPECTOR_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
EOF

# Run with credentials

docker run --rm \
  -v "$PWD:/scan" \
  --env-file .env \
  skillspector scan ./my-skill/

```

### Passing Credentials via Command Line

Alternatively, inject credentials directly using the `-e` flag to reference host environment variables:

```bash
docker run --rm \
  -v "$PWD:/scan" \
  -e SKILLSPECTOR_PROVIDER=anthropic \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  skillspector scan ./my-skill/

```

### Exporting Scan Results

To capture reports on your host system, specify an output path relative to the mounted `/scan` directory:

```bash
docker run --rm \
  -v "$PWD:/scan" \
  skillspector scan ./my-skill/ --format json --output report.json

```

## Creating a Persistent Docker Alias

For frequent use, create a shell alias that encapsulates the standard volume mount:

```bash
alias skillspector-docker='docker run --rm -v "$PWD:/scan" skillspector'

# Usage

skillspector-docker scan ./my-skill/ --no-llm

```

## Summary

- The **multi-stage Dockerfile** (lines 1-17) creates a minimal runtime image with the `skillspector` CLI available on the system `PATH` at `/app/.venv/bin`
- Mount your project directory to `/scan` to make files accessible inside the container environment
- Pass **LLM credentials** via `--env-file` or `-e` flags, as the image contains no hardcoded API keys
- Use `--no-llm` for offline environments requiring only static analysis capabilities
- The **Makefile** provides `make docker-build` as a convenient shortcut for image compilation

## Frequently Asked Questions

### Do I need Python installed locally to use the SkillSpector Docker image?

No. The Docker image is completely self-contained. The builder stage compiles everything into a virtual environment inside the container, and the runtime stage includes only the necessary Python binaries and dependencies. You only need Docker installed on your host system to run SkillSpector.

### How do I scan a skill directory located outside my current working directory?

Mount the specific directory to `/scan` using the absolute path in the `-v` flag. For example: `docker run --rm -v "/path/to/skill:/scan" skillspector scan /scan/`. The container treats `/scan` as its working directory, so adjust your target paths accordingly when referencing files inside the container.

### Can I integrate the SkillSpector Docker image into CI/CD pipelines?

Yes. The container exits with appropriate status codes based on scan results, making it suitable for automated pipelines. Mount your repository and add the `--format json` flag to parse results programmatically in subsequent pipeline steps. Ensure you inject LLM API keys via environment variables if running enhanced scans in automated environments.

### Where is the container's entrypoint defined in the source code?

The entrypoint is defined in the final lines of the `Dockerfile` (lines 16-17) and points to the `skillspector` command. This command is implemented in [`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py), which handles argument parsing and orchestrates the scanning logic. When you append arguments to `docker run`, they are passed directly to this CLI implementation.