# How to Run SkillSpector in Docker with Environment Variables

> Learn how to run SkillSpector in Docker using environment variables. Easily configure API keys and model settings by mounting volumes and using -e flags or env files for seamless integration.

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

---

**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`](https://github.com/NVIDIA/SkillSpector/blob/main/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`](https://github.com/NVIDIA/SkillSpector/blob/main/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`](https://github.com/NVIDIA/SkillSpector/blob/main/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.

```bash

# 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.

```bash

# 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:

```bash
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`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py).
- Configuration is injected at runtime via environment variables, which are read from [`src/skillspector/constants.py`](https://github.com/NVIDIA/SkillSpector/blob/main/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`](https://github.com/NVIDIA/SkillSpector/blob/main/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`](https://github.com/NVIDIA/SkillSpector/blob/main/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`](https://github.com/NVIDIA/SkillSpector/blob/main/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.