Harmony Proxy

A secure, pluggable proxy for data meshes — with first-class healthcare support (FHIR, DICOM/DICOMweb, JMIX).

---

🛠️ This project was built by Aurabox

Some of our other projects...

---

Overview

Harmony Proxy is a production-ready, extensible data mesh proxy/gateway for heterogeneous systems. It routes requests through configurable endpoints, middleware, and services/backends to connect systems that speak HTTP/JSON, FHIR, DICOM/DICOMweb, and JMIX.

Highlights:

• Multi-protocol: HTTP/JSON passthrough, FHIR, DICOM/DICOMweb (QIDO-RS/WADO-RS), JMIX
• Multi-content-type: Automatic parsing of JSON, XML, CSV, form data, multipart, and binary content
• Configurable pipelines: endpoints + ordered middleware + services/backends
• Hot configuration reload: zero-downtime updates for most config changes
• Authentication: JWT (recommend RS256 in production), optional Basic
• Transformations: JSON transforms (JOLT), DICOM↔DICOMweb bridging, JMIX packaging
• Runbeam Cloud Integration: Gateway authorization for autonomous API access with 30-day machine tokens
• Secure Token Storage: Encrypted filesystem storage for machine tokens (no configuration needed)
• Security: XXE prevention, CSV formula injection mitigation, configurable size limits
• Operationally sound: structured logging, local ./tmp storage convention

Status: under active development. For more information, visit https://harmonyproxy.com.

Who is this for?

• Platform teams building data meshes or integration hubs (healthcare and beyond)
• Developers integrating HTTP/JSON services and healthcare protocols (FHIR, DICOM/DICOMweb)
• Operators who need auditable, configurable request/response pipelines

Quick start

Install pre-built binaries

The fastest way to get started is with pre-built binaries for your platform. Download the latest release from GitHub Releases.

Supported platforms:

• Linux x86_64 (Ubuntu, Debian, Fedora, RHEL, etc.)
• Linux ARM64 (ARM64 servers)
• macOS Intel (x86_64)
• macOS Apple Silicon (ARM64)
• Windows x64

Linux x86_64

# Download the latest release
wget https://github.com/aurabx/harmony/releases/latest/download/harmony-x86_64-unknown-linux-gnu.tar.gz

# Download and verify SHA256 checksum
wget https://github.com/aurabx/harmony/releases/latest/download/harmony-x86_64-unknown-linux-gnu.sha256
sha256sum -c harmony-x86_64-unknown-linux-gnu.sha256

# Extract the archive
tar xzf harmony-x86_64-unknown-linux-gnu.tar.gz

# Make executable
chmod +x harmony

# Optional: Move to system path
sudo mv harmony /usr/local/bin/

Linux ARM64

# Download the latest release
wget https://github.com/aurabx/harmony/releases/latest/download/harmony-aarch64-unknown-linux-gnu.tar.gz

# Download and verify SHA256 checksum
wget https://github.com/aurabx/harmony/releases/latest/download/harmony-aarch64-unknown-linux-gnu.sha256
sha256sum -c harmony-aarch64-unknown-linux-gnu.sha256

# Extract the archive
tar xzf harmony-aarch64-unknown-linux-gnu.tar.gz

# Make executable
chmod +x harmony

# Optional: Move to system path
sudo mv harmony /usr/local/bin/

macOS Intel (x86_64)

# Download the latest release
curl -LO https://github.com/aurabx/harmony/releases/latest/download/harmony-x86_64-apple-darwin.tar.gz

# Download and verify SHA256 checksum
curl -LO https://github.com/aurabx/harmony/releases/latest/download/harmony-x86_64-apple-darwin.sha256
shasum -a 256 -c harmony-x86_64-apple-darwin.sha256

# Extract the archive
tar xzf harmony-x86_64-apple-darwin.tar.gz

# Remove quarantine attribute (required on macOS)
xattr -d com.apple.quarantine harmony

# Make executable (if needed)
chmod +x harmony

# Optional: Move to system path
sudo mv harmony /usr/local/bin/

macOS Apple Silicon (ARM64)

# Download the latest release
curl -LO https://github.com/aurabx/harmony/releases/latest/download/harmony-aarch64-apple-darwin.tar.gz

# Download and verify SHA256 checksum
curl -LO https://github.com/aurabx/harmony/releases/latest/download/harmony-aarch64-apple-darwin.sha256
shasum -a 256 -c harmony-aarch64-apple-darwin.sha256

# Extract the archive
tar xzf harmony-aarch64-apple-darwin.tar.gz

# Remove quarantine attribute (required on macOS)
xattr -d com.apple.quarantine harmony

# Make executable (if needed)
chmod +x harmony

# Optional: Move to system path
sudo mv harmony /usr/local/bin/

Windows x64

# Download the latest release (using PowerShell)
Invoke-WebRequest -Uri "https://github.com/aurabx/harmony/releases/latest/download/harmony-x86_64-pc-windows-msvc.tar.gz" -OutFile "harmony-x86_64-pc-windows-msvc.tar.gz"

# Download SHA256 checksum
Invoke-WebRequest -Uri "https://github.com/aurabx/harmony/releases/latest/download/harmony-x86_64-pc-windows-msvc.sha256" -OutFile "harmony-x86_64-pc-windows-msvc.sha256"

# Verify checksum
Get-FileHash -Algorithm SHA256 harmony-x86_64-pc-windows-msvc.tar.gz
# Compare the output with the contents of the .sha256 file

# Extract the archive (tar is built into Windows 10+)
tar xzf harmony-x86_64-pc-windows-msvc.tar.gz

# Optional: Add to PATH
# Move harmony.exe to a directory in your PATH, or add the current directory to PATH

Running the binary

Once installed, run Harmony with a configuration file:

# If in current directory
./harmony --config /path/to/config.toml

# If installed to /usr/local/bin or in PATH
harmony --config /path/to/config.toml

Note: To use the example configurations, you'll need to clone this repository or download them separately from the examples directory.

---

Local development

For contributors who want to build from source:

Prerequisites:

• Rust (stable) via rustup
• macOS or Linux

Build and run with the example configuration:

# Build
cargo build

# Run the basic echo example
cargo run -- --config examples/basic-echo/config.toml

Try the basic echo endpoint:

# In another shell
curl -i http://127.0.0.1:8080/echo

If configured, you should receive an echoed response from the sample backend. Explore more examples under the examples/ directory (each has its own README).

Docker

Option 1 – Run with Docker Compose (recommended)

For local development or quick testing:

# Build and start containers
docker compose up

# Alternatively, to rebuild and restart cleanly
docker compose up --build --force-recreate -d

# Test the service
curl -i http://localhost:8080/echo

Compose uses the included Dockerfile.build so everything builds from source inside Docker—no Rust toolchain required on the host.

Ports

• 8080 – Main service endpoints
• 9090 – Management API (if enabled)

---

Option 2 – Build and run manually (from prebuilt or local binaries)

If you have prebuilt binaries or are running from CI output, use the lean runtime image (Dockerfile):

# Build image from prebuilt binaries (fast path)
docker build -t harmony .

# Run with default config
docker run -p 8080:8080 -p 9090:9090 \
  -v $(pwd)/config:/etc/harmony:ro \
  harmony

# Run with example config
docker run -p 8080:8080 \
  -v $(pwd)/examples:/examples:ro \
  harmony --config /examples/basic-echo/config.toml

If you'd rather build everything from scratch (no prebuilt binaries), specify the full build image explicitly:

docker build -f Dockerfile.build -t harmony .
docker run -p 8080:8080 harmony

---

Option 3 – Use the published image

Once your CI workflow pushes to GHCR:

docker pull ghcr.io/aurabx/harmony:latest
docker run -p 8080:8080 -p 9090:9090 ghcr.io/aurabx/harmony:latest

---

This layout clarifies:

• Compose / Dockerfile.build → full source build (developer-friendly)
• Dockerfile → prebuilt-binary runtime (used by CI and GHCR images)
• Published image → fastest start for end-users

Configuration

Harmony's configuration is file-based (TOML) and can include additional pipeline/transform files from a directory.

Examples (each with README, config, and pipelines):

• examples/basic-echo/ - Simple HTTP passthrough
• examples/fhir/ - FHIR with authentication
• examples/transform/ - JOLT transformations
• examples/fhir-to-dicom/ - Protocol translation
• examples/jmix/ - JMIX packaging
• examples/dicom-backend/ - DICOM SCU operations
• examples/dicom-scp/ - DICOM SCP endpoint
• examples/dicomweb/ - DICOMweb support
• examples/jmix-to-dicom/ - JMIX to DICOM workflow

Core building blocks:

• Networks: bind addresses/ports and optional WireGuard
• Endpoints: public-facing routes (HTTP/FHIR/DICOMweb)
• Middleware: ordered request/response modifiers (e.g., JWT auth, transforms)
• Services/Backends: where work is performed (e.g., DICOMweb client, echo service)
• Storage: project-local filesystem path (./tmp by default)
• Hot-reload: automatic config updates with zero-downtime for most changes

See docs/configuration/configuration-file.md, docs/configuration/endpoints.md, docs/configuration/middleware.md, and docs/configuration/backends.md for details.

Documentation

• Docs index: docs/index.md
• Getting started: docs/guides/getting-started.md
• Configuration: docs/configuration/configuration-file.md
• Content types: docs/configuration/content-types.md (JSON, XML, CSV, multipart, binary)
• Endpoints: docs/configuration/endpoints.md
• Middleware: docs/configuration/middleware.md
• Backends: docs/configuration/backends.md
• Router: docs/architecture/router.md
• Envelope model: docs/architecture/envelope.md
• Management API: docs/api/management-api.md (includes Runbeam Cloud authorization)
• DIMSE integration: docs/integrations/dicom-dimse.md
• Testing: docs/guides/testing.md
• Security: docs/security/overview.md
• System description: docs/architecture/overview.md

System requirements

• Rust (stable)
• macOS or Linux runtime environment
• DCMTK (required for DICOM SCU operations: C-GET and C-MOVE; optional for persistent C-STORE SCP)
  • macOS (Homebrew): brew install dcmtk
  • Debian/Ubuntu: sudo apt-get install dcmtk

Security

• JWT: prefer RS256 with strict algorithm enforcement; validate exp/nbf/iat and iss/aud where applicable
• Encryption: AES-256-GCM with ephemeral public key, IV, and authentication tag encoded in base64
• Secrets: do not commit secrets; use environment variables or secret managers
• Temporary files: prefer ./tmp within the working directory

Environment variables:

export RUST_LOG=harmony=info                       # overrides logging.log_level
export RUNBEAM_ENCRYPTION_KEY=AGE-SECRET-KEY-1...  # encrypts the stored machine token
./harmony --config config.toml

• Environment Variables: every variable Harmony reads, with defaults and precedence.
• Managing Secrets: key generation, rotation, and secret managers.
• Encryption Key Management: CLI-managed, environment, auto-generated, and pre-provisioned keys and tokens.

Contributing

We welcome issues and pull requests! Please read CONTRIBUTING.md and DEVELOPER.md for workflow and development standards. Our community guidelines are defined in CODE_OF_CONDUCT.md.

License and commercial use

Harmony Proxy is licensed under the Apache License, Version 2.0.

Important: You may freely download, use, and modify Harmony Proxy for internal use and self-hosted deployments. Reselling Harmony Proxy as a hosted service or embedding it in a commercial offering requires a commercial licence from Aurabox Pty Ltd. Contact support@aurabox.cloud for enquiries.

Support

• General questions and support: hello@aurabox.cloud
• Security or conduct concerns: hello@aurabox.cloud

---

🛠️ This project was built by Aurabox

Some of our other projects...

---