Spark Pulse
Spark Pulse is a web control plane for spark-vllm-docker. It brings recipe discovery, deployment management, live monitoring, cache cleanup, and configuration into one interface for NVIDIA DGX Spark hardware.
License: MIT — Copyright © 2026 Kharkevich Engineering Lab
Disclaimer: This project is not sponsored by, endorsed by, or affiliated with NVIDIA Corporation or any of its subsidiaries. NVIDIA, DGX, and related trademarks are property of their respective owners.
Features
- Recipe browsing - Explore deployment recipes, model variants, and mod combinations in a clean catalog view.
- Deployment jobs - Launch deployments, watch live logs, inspect status, and stop running jobs from the UI.
- Real-time monitoring - Track GPU, CPU, RAM, and disk usage with streaming updates.
- Cache management - Review and clean Hugging Face, wheel, ccache, Triton, and related caches.
- Settings and auth - Configure the backend path, defaults, and OIDC authentication.
- MCP server - Expose the same operations to Model Context Protocol clients and automation.
Screenshots
Recipes
Browse available deployment recipes, inspect model details, and compare supported variants at a glance.
Jobs
Monitor deployments, stream logs, and manage running jobs without leaving the dashboard.
Monitoring
Watch GPU, CPU, and disk usage in real time alongside active GPU processes.
Installation
Install the published package from PyPI:
python3 -m pip install spark-pulse
This installs the spark-pulse command-line interface.
Usage
Start the web app after installation:
spark-pulse start
Then open the UI in your browser. The default port is 8100 unless you changed it in configuration.
Common runtime commands:
# Start the MCP server for assistants and automation
spark-pulse mcp
# Install and manage the app as a systemd service
spark-pulse install
spark-pulse status
spark-pulse start-service
spark-pulse stop-service
spark-pulse uninstall
Add --user to any of the service commands if you want a user-scoped systemd unit.
Authentication is optional. When enabled, Spark Pulse redirects users through your configured OIDC provider and protects the UI and API routes.
Configuration
Spark Pulse reads settings from config.yaml (bundled with the package) and merges user overrides from ~/.config/spark-pulse/settings.json. Environment variables take highest priority.
config.yaml Reference
| Key | Type | Default | Description |
|---|---|---|---|
spark_vllm_path |
string | /tmp/spark-vllm-docker |
Absolute path to the spark-vllm-docker installation directory. |
webui_port |
int | 8100 |
TCP port the web UI listens on. |
default_container |
string | vllm-node |
Default Docker container name for deployments. |
default_gpu_mem_util |
float | 0.8 |
Default GPU memory utilization fraction (0.0–1.0). |
default_port_range_start |
int | 9000 |
Start of the ephemeral port range for deployments. |
default_port_range_end |
int | 9100 |
End of the ephemeral port range for deployments. |
job_retention_days |
int | 7 |
Number of days to retain completed job records. |
cluster_enabled |
bool | false |
Enable multi-node cluster mode. |
mcp_enabled |
bool | true |
Enable the MCP server endpoint. |
mcp_path |
string | /mcp |
HTTP path for the MCP server. |
mcp_api_token |
string | (empty) | Optional API token to protect MCP requests. |
auth_enabled |
bool | false |
Enable OIDC authentication. |
oidc_provider_url |
string | (empty) | OIDC provider URL (e.g. https://keycloak.example.com/realms/myrealm). |
oidc_client_id |
string | (empty) | OIDC client ID. |
oidc_client_secret |
string | (empty) | OIDC client secret — stored securely in ~/.config/spark-pulse/secrets.json. |
Environment Variable Overrides
The following environment variables override their corresponding config keys:
| Environment Variable | Config Key | Description |
|---|---|---|
SPARK_VLLM_PATH |
spark_vllm_path |
Override the spark-vllm-docker path. |
WEBUI_PORT |
webui_port |
Override the web UI port. |
File Locations
| File | Purpose |
|---|---|
config.yaml |
Bundled defaults (read-only, overwritten on package update). |
~/.config/spark-pulse/settings.json |
Persistent user overrides (survives package updates). |
~/.config/spark-pulse/secrets.json |
Securely stored secrets (mode 0600). |
Example: Enabling OIDC Authentication
# config.yaml or settings.json
auth_enabled: true
oidc_provider_url: https://keycloak.example.com/realms/myrealm
oidc_client_id: spark-pulse
Then set the client secret via the UI Settings page or directly in secrets.json:
{
"oidc_client_secret": "your-secret-here"
}
Development Mode with Mock OIDC Provider
For local development, Spark Pulse ships with convenience scripts that start a mock OIDC provider alongside the dev server. This lets you test the full SSO login flow without a real identity provider.
Full stack (backend + frontend with hot-reload):
./scripts/run-dev-oidc-full.sh
This script:
- Starts the mock OIDC provider on
http://localhost:9400 - Creates
~/.config/spark-pulse/settings.jsonandsecrets.jsonwith dev credentials - Launches the backend with
--reload(serves both API and built frontend)
Backend only (for API testing):
./scripts/run-dev-oidc.sh
Dev credentials (both scripts):
- Provider URL:
http://localhost:9400 - Client ID:
spark-pulse-dev - Client Secret:
dev-secret
To stop, press Ctrl+C — the scripts clean up all background processes.
Development
Clone the repository and install local development dependencies:
python3 -m pip install -e ".[dev]"
Build the frontend and run the app locally:
cd web && npm install && npm run build && cd ..
./scripts/run-dev-server.sh
Useful development commands:
./scripts/run-backend.sh
./scripts/run-production.sh
./scripts/build-ui.sh
pytest
python -m build
API
The app exposes REST endpoints under /api/* for recipes, deployments, memory, cache, and settings, plus /auth/* routes for OIDC login and session handling.
License
MIT. See LICENSE.
1 maintainer
Metadata
1 maintainer
Release files for spark-pulse 1.14.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| spark_pulse-1.14.0.tar.gz | 888.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| spark_pulse-1.14.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.7 MB
Release files / spark_pulse-1.14.0.tar.gz
| Download URL | spark_pulse-1.14.0.tar.gz |
|---|---|
| Size | 888.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ba537f62d266fca870b9261adc592e57ab57e92939510aae58a25e4a6825938e
|
|
BLAKE2b-256 checksum How to use checksums |
46777ed4095e818b3bc35cb9795c27170f3c096b55691f7910865503be7b7129
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 4, 2026.
Transparency logRelease files / spark_pulse-1.14.0-py3-none-any.whl
| Download URL | spark_pulse-1.14.0-py3-none-any.whl |
|---|---|
| Size | 779.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6a447b8e055c720c66ccbef937e3cc6447f9fdc123fede335655f7fbd7d4eb3f
|
|
BLAKE2b-256 checksum How to use checksums |
5976db61e28f8fe8b8084cfc52fd15d8f85f8a122ecdcbc15086b36a6ce2bfb4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 4, 2026.
Transparency log
