DSpark Environment Variable Reference: Complete Configuration Guide

The authoritative DSpark environment variable reference is maintained in the docs/ENVS.md file within the MiaAI-Lab/DeepSeek-v4-Flash-DSpark-2x-DGX-Spark repository, which catalogs every variable recognized by the vLLM-based runtime along with grouped applicability and default behaviors.

Deploying DeepSeek-v4-Flash via DSpark requires precise tuning of runtime parameters through environment variables to optimize inference on DGX infrastructure. This guide identifies the official reference locations, explains the configuration hierarchy, and provides working examples for customizing the Anemll and Stage-C execution paths.

The Authoritative Reference: docs/ENVS.md

The definitive DSpark environment variable reference resides at docs/ENVS.md in the repository root. This markdown document serves as the single source of truth for the runtime configuration, listing every variable the vLLM-based engine recognizes.

The file organizes variables into three functional groups:

• Anemll-only variables – Specific to the Anemll execution backend
• Stage-C-only variables – Applicable exclusively when running Stage-C overlays
• Generic variables – Universal settings affecting all execution modes

Each entry includes the variable name, purpose description, and default value where applicable. The document tracks implementation details as they evolve in the MiaAI-Lab/DeepSeek-v4-Flash-DSpark-2x-DGX-Spark codebase.

Starter Configuration Templates

.env.dspark.example

For rapid deployment, reference .env.dspark.example, which provides a production-ready template mirroring the defaults used by Docker launch scripts. This file demonstrates the expected variable names and value formats without requiring deep navigation of the full documentation.

# Copy the example file to create your active configuration

cp .env.dspark.example .env.dspark

# Edit critical parameters for your hardware profile

# VLLM_USE_BREAKABLE_CUDAGRAPH=0       # Disable breakable graphs for stability

# VLLM_USE_B12X_MOE=1                 # Enable B12X MoE optimization path

# DSPARK_MAX_INFLIGHT_PREFILLS=2     # Limit concurrent prefills to 2

Docker Compose Integration

The docker-compose.dspark.yml file automatically consumes the .env.dspark file at startup, injecting values into both head and worker containers. The launcher scripts start-deepseek-v4-flash-dspark.sh and start-tp3.sh orchestrate this process, reading the environment file before container initialization.

# Launch the stack with environment variables loaded from .env.dspark

docker compose -f docker-compose.dspark.yml up -d

Key Variable Categories

vLLM-Runtime Variables

Variables prefixed with VLLM_ control the underlying vLLM engine behavior:

• VLLM_USE_BREAKABLE_CUDAGRAPH – Controls CUDA graph optimization strategies
• VLLM_USE_B12X_MOE – Toggles the B12X mixture-of-experts execution path
• VLLM_API_KEY – Sets single-key authentication mode (mutually exclusive with DSPARK_API_KEYS)

DSpark-Specific Variables

Variables prefixed with DSPARK_ manage orchestration and high-level behaviors:

• DSPARK_MAX_INFLIGHT_PREFILLS – Limits concurrent prefill operations to manage VRAM
• DSPARK_API_KEYS – Enables multi-key authentication with space-separated values
• DSPARK_BOOT_SHAPE_WARMUP – Controls optional warm-up procedures during initialization

Authentication Modes

The system supports two mutually exclusive authentication schemes as implemented in the entrypoint logic. Setting both VLLM_API_KEY and DSPARK_API_KEYS simultaneously causes the container to reject the configuration and exit.

# Option 1: Single key mode

VLLM_API_KEY=sk-my-openai-key

# Option 2: Multiple key mode

DSPARK_API_KEYS="key1 key2 key3"

Practical Configuration Examples

Runtime Verification

After startup, verify variable injection inside running containers:

# Query a specific variable inside the head container

docker exec -it dspark-head bash -c 'echo $VLLM_USE_B12X_MOE'

# Expected output: 1

Host-Only Variables

Certain variables like DSPARK_BOOT_SHAPE_WARMUP operate only on the host side before container launch. These are consumed by helper scripts rather than the vLLM runtime.

# Enable pre-launch warm-up sequence on host

export DSPARK_BOOT_SHAPE_WARMUP=1
./scripts/boot-shape-warmup.sh

Supplementary Documentation

While docs/ENVS.md provides the exhaustive reference, docs/SETUP.md offers contextual guidance on when to enable specific Stage-C overlays and Anemll configurations. Use SETUP.md for architectural decisions and ENVS.md for parameter lookup.

Summary

• The complete DSpark environment variable reference is located at docs/ENVS.md in the MiaAI-Lab repository.
• .env.dspark.example provides a working template with sensible defaults for Docker deployments.
• Variables use prefixes to denote scope: VLLM_* for runtime engine settings, DSPARK_* for orchestration and authentication.
• docker-compose.dspark.yml automatically loads .env.dspark at container startup.
• Authentication modes are mutually exclusive—choose either VLLM_API_KEY or DSPARK_API_KEYS, never both.

Frequently Asked Questions

Where is the complete DSpark environment variable reference maintained?

The authoritative list resides in docs/ENVS.md within the MiaAI-Lab/DeepSeek-v4-Flash-DSpark-2x-DGX-Spark repository. This file catalogs every recognized variable, groups them by applicability (Anemll-only, Stage-C-only, or generic), and documents their default behaviors and purposes.

How do I quickly configure DSpark without reading the full documentation?

Copy .env.dspark.example to .env.dspark and edit the values relevant to your hardware. This example file contains the default values used by the Docker Compose launch scripts and serves as a practical quick-start reference for common deployment scenarios.

What distinguishes VLLM_* variables from DSPARK_* variables?

Variables prefixed with VLLM_ control the underlying vLLM inference engine (such as VLLM_USE_B12X_MOE for mixture-of-experts optimization), while DSPARK_* variables manage DSpark-specific orchestration features like DSPARK_MAX_INFLIGHT_PREFILLS for concurrency limiting and DSPARK_API_KEYS for multi-key authentication.

Can I configure multiple API keys for DSpark access?

Yes, use the DSPARK_API_KEYS environment variable with space-separated values to enable multi-key authentication. Note that this is mutually exclusive with VLLM_API_KEY; the container entrypoint will reject the configuration and fail to start if both variables are defined simultaneously.

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