How to Run SkillSpector in Docker with Environment Variables

To run SkillSpector in Docker with environment variables, mount your target code volume and pass configuration via -e flags or an --env-file, allowing the containerized CLI to access API keys and model settings through os.getenv calls in src/skillspector/constants.py.

NVIDIA/SkillSpector provides a containerized deployment option that packages the Python runtime, the uv dependency manager, and the CLI entry-point into a single image. When you run SkillSpector in Docker with environment variables, you eliminate the need to install Python or dependencies locally while keeping sensitive configuration like API keys outside the container image.

How the SkillSpector Docker Image Works

According to the Dockerfile in the repository, the image builds on an official Python base, installs the uv package manager, copies the repository source into the container, and sets the default command to the SkillSpector CLI (skillsp). The CLI implementation resides in src/skillspector/cli.py, which is invoked automatically when the container starts. This design encapsulates the entire runtime and ensures consistent behavior across different host environments.

Configuring Environment Variables

Configuration is externalized through environment variables rather than baked into the image. The repository provides an .env.example file that documents the required variables, including API keys like OPENAI_API_KEY and NV_BUILD_TOKEN, as well as model selectors.

Inside the container, the Python code retrieves these values using os.getenv calls defined in src/skillspector/constants.py. This approach allows you to inject sensitive credentials at runtime without rebuilding the image or committing secrets to version control.

Running the Container

Pull the Pre-built Image or Build Locally

NVIDIA distributes a pre-built image via the NVIDIA Container Registry (NVCR), or you can build locally from the Dockerfile if you require custom modifications.

# Option A: Pull the official image

docker pull nvcr.io/nvidia/skillspector:latest

# Option B: Build locally

docker build -t skillspector:local .

Mount Your Code and Pass Environment Variables

To analyze a repository, bind-mount your local source code into the container and supply the environment variables using either individual -e flags or a single --env-file directive.

# Create env file from template

cp .env.example .env

# Edit .env to set OPENAI_API_KEY and NV_BUILD_TOKEN

# Run with env file

docker run --rm \
  --env-file .env \
  -v "$(pwd)/sample_repo:/workspace" \
  nvcr.io/nvidia/skillspector:latest \
  skillsp analyze /workspace

The --rm flag removes the container automatically after execution, while -v mounts your target directory to /workspace inside the container. The skillsp analyze command processes the mounted code using the API keys provided via the environment file.

For one-off commands or CI pipelines, you can pass variables directly:

docker run --rm \
  -e OPENAI_API_KEY=sk-your-key-here \
  -e NV_BUILD_TOKEN=your-token-here \
  -v "$(pwd)/sample_repo:/workspace" \
  skillspector:local \
  skillsp report --format sarif /workspace

Summary

• The SkillSpector Docker image packages the Python runtime, uv dependency manager, and the skillsp CLI entry-point defined in src/skillspector/cli.py.
• Configuration is injected at runtime via environment variables, which are read from src/skillspector/constants.py using os.getenv.
• Use the .env.example file as a template to create your own .env file with required values like OPENAI_API_KEY and NV_BUILD_TOKEN.
• Mount your target codebase using -v and pass configuration via --env-file or -e flags to run analyses without installing dependencies locally.

Frequently Asked Questions

How do I pass multiple environment variables to the SkillSpector container?

You can pass multiple variables by repeating the -e flag for each key-value pair, or by listing them all in a file and referencing it with --env-file .env. The container loads these variables into the shell environment, where src/skillspector/constants.py accesses them via os.getenv.

Where does SkillSpector read environment variables from inside the container?

The application reads environment variables using os.getenv calls centralized in src/skillspector/constants.py. This module defines the canonical names for configuration values such as API keys and model selectors, which are expected to be present in the container's environment at startup.

Can I build the Docker image locally instead of using the pre-built image?

Yes. The repository includes a Dockerfile that builds on an official Python base image, installs uv, and copies the source code. Run docker build -t skillspector:local . from the repository root to create a local image tagged skillspector:local, then use that tag in your docker run commands.

What is the default entrypoint when running the SkillSpector container?

The Dockerfile sets the default command to the SkillSpector CLI (skillsp), which is implemented in src/skillspector/cli.py. This means any arguments you pass after the image name in docker run are forwarded directly to the skillsp command, allowing you to invoke sub-commands like analyze or report naturally.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}