Skip to main content

Neuropacs Agent

Overview​

The Neuropacs Agent is an on-premises software solution designed to operate within your data center, seamlessly integrating with your existing infrastructure while securely interfacing with the Neuropacs Cloud. It establishes an encrypted connection to transmit medical imaging for analysis, manage orders, retrieve reports, and automatically route them to designated destinations.

The Agent also supports fully on-premises workflows to provide an additional layer of data protection and control. With local quality control and preprocessing performed entirely within your internal network, sensitive data remains on site at all times—never leaving your environment.

Key Benefits​

  • Direct DICOM Integration: Seamless connection to PACS systems and other DICOM-supported archives as a standard DICOM destination.
  • Integrated Web Portal: Centralized platform to configure workflows, monitor system activity, and manage studies.
  • Automated Workflow: Automatic routing, quality control, and report delivery without manual intervention.
  • Secure Processing: Encrypted connections and configurable de-identification rules ensure data protection.
  • Comprehensive Monitoring: Real-time logs and transparent tracking of all system operations.
  • Healthcare Compliant: Full compliance with healthcare regulations and standards.

Getting Started​

Usage Guide (PDF)​

Download the Neuropacs Agent Usage Guide

Tips & Best Practices​

Supported Environments​

Supported Operating Systems​

  • Native Linux Hosts (Ubuntu 22.04+ recommended) - Modern Linux distributions with support for Docker Engine and Docker Compose
  • Windows Hosts - Windows 10/11 Pro, Enterprise, Education, and Server with Hyper-V/VMware virtualization capabilities
  • macOS Hosts - Modern macOS versions with Docker Desktop or VMware Fusion

Supported Virtualization Platforms​

  • VMware (VMware Workstation, VMware Fusion, VMware vSphere)
  • Hyper-V

Supported Cloud Deployments​

  • Amazon Web Services (AWS)
  • Microsoft Azure
  • Google Cloud Platform (GCP)

Optimal Performance​

  • Configure routing rules to send only relevant studies
  • Monitor system resources and storage capacity
  • Schedule maintenance tasks during low-activity periods

Security Best Practices​

  • Enable all available de-identification options
  • Regularly update Agent software and security patches
  • Monitor access logs and user activity
  • Enable TLS for secure network communication

Workflow Optimization​

  • Set up automated routing for common study types
  • Configure notification preferences for critical events deliverable via webhook or email
  • Use quality control reports to improve upstream processes
  • Leverage group processing for high-volume environments

Releases​

Safe Transactions + Structural Updates

v0.1.68
Release

The Neuropacs Agent now ensured reliable transactions and order lifecycle with a refined project structure

v0.1.68 focuses on safer, transactional local-processing Docker image updates (including an API endpoint + UI action), improved standalone updater rollback retention/cleanup, and updated test/docs/CI alignment.

  • Fix docker ports and app environment to simplify configuration and setup
  • Update packer to accommodate new fixed port config
  • IO_BASE_DIR is stable and included in all Docker builds, removed fallback/conditionals related to this constant
  • Remove unused derived Docker path environment variables; app paths now derive from IO_BASE_DIR while local processing workspace variables remain unchanged for backwards compatibility
  • Add a generic notifications audit table for sent, failed, and suppressed notification events
  • Add system metric notifications for high CPU, high memory, high swap, low disk space, and metric recovery events
  • Add configurable system metric alert toggles, thresholds, and cooldown settings to the Notifications settings UI
  • Evaluate system metric alert thresholds during heartbeat dispatch without blocking heartbeat delivery if alerting fails
  • Add PHI Shield controls for study/accession identifiers in Studies and Results, plus sensitive metadata dialog sections
  • Refine compact PHI Shield table styling so reveal controls fit beside identifiers without covering row content
  • Scrub private DICOM tags during deidentification while retaining allowlisted DTI acquisition metadata needed for conversion
  • Always remove accession numbers from deidentified DICOM output while keeping cloud accession sync controlled by sendAccessionNumber
  • Sync patient age/sex plus explicitly allowlisted deidentified acquisition metadata to the cloud; accession numbers still require the existing sendAccessionNumber setting
  • Route JSON sidecar, manual DICOM metadata, and QC metadata cloud updates through the same deny-by-default cloud-safe metadata filter
  • Reject nonstandard patient age syntax during QC while accepting common 90+ Safe Harbor variants and normalizing them to 90
  • Reject unsupported patient sex values during QC; only M/MALE and F/FEMALE are accepted
  • Remove PHI identifiers and redact identifier-like text inside nested DICOM sequence items during deidentification
  • Avoid logging raw patient demographic or accession metadata values during metadata extraction and local metadata updates
  • Show DICOM TLS certificate expiration in Settings using an RBAC-mapped certificate status endpoint
  • Preserve Studies and Results pagination across refreshes, auto-refresh remounts, and order cancellation refreshes
  • Add first/last page controls, numbered page navigation, and direct page jump controls to Studies and Results tables
  • Remove nonfunctional filter toggle buttons from Studies and Results headers
  • Reduce Studies and Results table pagination stalls by deferring search filtering and avoiding repeated per-row config/date work
  • Add durable DICOM receive activity tracking so slow or still-active PACS associations are not marked stable too early
  • Move imaging cleanup after committed DB state for upload completion and stuck upload recovery to avoid unrecoverable file deletion on DB failure
  • Treat duplicate C-STORE retries as successful when the existing stored file matches the same SOP Instance UID
  • Add automatic DICOM receiver restart with capped backoff after unexpected Python receiver exits
  • Add an optional sending AE title allowlist for restricting which DICOM applications can send studies
  • Parse external cloud order groups from list-orders and render external results under their batch_name groups in Results.
  • Add configurable general database record retention for notifications, delivery history, terminal local processing jobs, and token cache records. Retention defaults to indefinite unless explicitly configured.
  • Refactored log search to enable compact query results and caching for performance.
  • Add customized DICOM stabilization period controlled by config and modifiable in the Settings page
  • Improve standalone container first-run setup prompts with API key confirmation, required-field retries, option validation, and final configuration review.
  • Add conservative cleanup and retry handling for failed standalone first-run setup, plus opt-in aggressive cleanup for removing setup containers and named Docker volumes after failure.

SSO/SAML + RBAC Support + TLS/HTTPS configuration support

v0.1.67
Release

The Neuropacs Agent now supports SSO/SAML and Role-based access control (RBAC).

This update adds comprehensive SAML 2.0 SSO, RBAC, audit logging, and TLS/HTTPS configuration support for the Agent while preserving backward compatibility with existing local password authentication. It also improves security, deployment hygiene, and operational reliability through stronger TLS settings, certificate validation, SAML assertion protections, expired-state handling, synchronized cloud/local status updates, and isolated release channels for production, staging, and development.

  • Added SAML 2.0 Single Sign-On support for the agent web interface, enabling authentication via Microsoft Entra ID, ADFS, or any SAML 2.0-compliant identity provider
  • Added configurable authentication modes: Local Password Only, SAML SSO + Local Password, and SAML SSO Only (with optional break-glass local password fallback)
  • Added "Sign in with SSO" button on the login screen when SAML is enabled, with the existing password form preserved for backward compatibility
  • Added SAML SSO + RBAC configuration section in Settings with fields for IdP Entity ID, SSO URL, certificate, SP Entity ID, SP Base URL, NameID format, and assertion signing requirements
  • Added IdP metadata auto-import: paste a federation metadata URL and click "Fetch" to auto-populate IdP Entity ID, SSO URL, SLO URL, and certificate
  • Added SP metadata endpoint (/api/saml/metadata) for IdP configuration
  • Added SP-initiated Single Logout (SLO) with IdP redirect when an SLO URL is configured
  • Added Sign Out button to the navigation bar (visible for both SAML and password-authenticated sessions)
  • Added HTTPS enforcement for SAML in production (blocks SAML login/ACS over non-localhost HTTP)
  • Added audience/issuer validation on SAML assertions to prevent assertion relay attacks
  • Added SAML response replay protection via InResponseTo request ID caching
  • Added rate limiting on the SAML Assertion Consumer Service endpoint (20 requests/IP/minute)
  • Added IdP certificate validation on settings save (rejects invalid PEM/X.509 certificates with a clear error)
  • Added automatic SAML session invalidation when SAML configuration changes (IdP cert, SSO URL, entity IDs, or SAML enabled/disabled toggle)
  • Added sliding-window SAML session renewal in the auth middleware, matching existing local-password session renewal behavior
  • Added user-friendly error display on the login screen when SAML authentication fails (replaces raw 401 responses)
  • Added structured audit logging for SAML login success, login failure, and logout events with user principal, client IP, and user agent
  • Added database migration (20260512_add_saml_sso_config.sql) to add SAML configuration fields to existing agent installs
  • Added @node-saml/node-saml dependency for SAML 2.0 protocol handling
  • All changes are fully backward compatible: existing agents using service username/password authentication are unaffected
  • index.js: Added minVersion: "TLSv1.2" and an explicit strong cipher list to the HTTPS server options.
  • index.js + SettingsPage.jsx + receiver.py: Upload response now returns filename (e.g. server.crt) instead of the full container path. Frontend stores the filename. receiver.py gained _resolve_dicom_tls_path() which resolves bare filenames against the canonical directory while still accepting absolute paths from existing configs.
  • index.js: Added PEM content validation after file upload — checks for -----BEGIN CERTIFICATE----- for certs and -----BEGIN ... PRIVATE KEY----- for keys. Rejects with a clear error message if mismatched.
  • index.js: Added a crypto.X509Certificate check at startup that logs an error if the cert is expired, a warning if it expires within 30 days, or an info-level confirmation otherwise. Wrapped in try/catch so older Node versions degrade gracefully.
  • index.js + SettingsPage.jsx: Added POST /api/https-tls/upload-cert endpoint that saves certs to IO_BASE_DIR/certs/https/, validates PEM content, and updates .env (TLS_ENABLED, TLS_CERT_PATH, TLS_KEY_PATH, TLS_CA_PATH) via updateEnvFile. Added an "HTTPS / TLS" accordion in the settings UI with upload buttons for cert, key, and CA, which triggers the existing restart-required banner.
  • docker-entrypoint.sh: Now checks for tls_cert.pem/tls_key.pem (preferred) first, falls back to cert.pem/key.pem (legacy) with a deprecation warning. Help text updated to show preferred names.
  • Added EXPIRED to the failedCount calculation in computeBatchStatus
  • Deleted "test-certs" folder from repo
  • js/rbac.js — loads permissions.json, pre-computes role→actions sets, exports requireRole(action) middleware factory and enforceRoutePermissions middleware that auto-resolves the action from the routes map using a simple Map lookup with wildcard fallback for parameterized paths.
  • js/saml.js — added resolveRoleFromProfile() that matches IdP group claims (checking several common attribute names) against samlAdminGroup/samlUserGroup config. createSamlSessionToken() now accepts a config param and embeds the resolved role in the token payload.
  • index.js — auth middleware now sets req.user.role: "admin" for local password sessions (including no-password legacy mode), and the role from the SAML token payload for SSO sessions. enforceRoutePermissions is wired as a single middleware after the auth middleware. Also imports rbac module and passes cfg to SAML token creation in the ACS route and session renewal.
  • db/configure.sql — added samlAdminGroup and samlUserGroup defaults.
  • db/migrations/20260512_add_saml_sso_config.sql — added _m12/_m13 migration blocks for the two new fields.
  • Now update cloud status on local status update to remain synched between states
  • Update channels for production, staging, and dev for isolated releases

Performance updates and bug fixes

v0.1.66
Release

General performance improvements and bug fixes

This update improves upload reliability, cleanup, and processing correctness by fixing silent failure paths, adding retries/integrity checks/abort handling, preventing orphaned orders, improving metadata handling, and hardening edge cases like mixed DICOM/NIfTI folders, system files, expired states, and stuck connections. It also includes performance, maintainability, and security improvements such as progress throttling, memoized file rendering, UI/code cleanup, Docker-native install deprecation, Swagger updates, and package security patches.

  • Updated Swagger docs
  • Addressed bug related to special characters in JSON sidecars causing orphaned studies that silently fail
  • Implemented retry mechanism for sending metadata to API - this is NECESSARY for processing (demographics)
  • Remove client-side upload and per-file retries
  • Detect and reject mixed folder with DICOM and NIfTI
  • silent-skip system files (5 minute fix, big UX win for Mac users)
  • crypto.randomUUID() on the server fallback (one-line fix, eliminates a silent-data-loss path)
  • Explicit "abandon order" call from the client + cleanup in markManualUploadFailed (prevents orphaned UPLOADING rows and stale receiving/ dirs)
  • Beforeunload guard while uploading (one-line fix, prevents user error)
  • Per-file XHR timeout (one-line, lets retries actually retry on stuck connections)
  • NIfTI bundle consistency warning (basename prefix check)
  • Confirm downstream is hierarchy-agnostic (5 minutes of grep)
  • Upload abort button (medium complexity, real value)
  • Upload SHA-256 integrity (medium complexity, gold standard)
  • Skip incrementManualUploadProgress for non-zip uploads — biggest win. Filesystem walk at finalize is the source of truth. Keep increments for ZIP uploads (where the receiving-dir walk is skipped because extraction adds many files).
  • Throttle frontend progress — only emit when integer percent changes per file. Drops re-renders from ~thousands per upload to ~hundreds total.
  • Memoize the file list — wrap the ListItem rendering in React.memo so progress updates don't re-render 1000 items every tick.
  • Drop getLocalProcessingEnabled and getCachedToken from /api/upload-file — neither is actually used in this handler. Saves a DB round-trip per file.
  • Moved unzip to py/stable_check.py instead of in upload endpoint - better design
  • Reorganized UI files
  • Removed unused code
  • Added custom private tag handling for default overrides
  • Deprecate install.sh - Docker-container-native install now only method
  • Security patches (package.json and frontend/package.json)
  • BUG - added 'EXPIRED' state to cleanup

Last updated: May 22, 2026