{
  "markdown": "<div align=\"center\">\n  <h1>Harmony Proxy</h1>\n  <p>\n    A secure, pluggable proxy for data meshes — with first-class healthcare support (FHIR, DICOM/DICOMweb, JMIX).\n  </p>\n  <p>\n    <a href=\"https://github.com/aurabx/harmony/actions/workflows/rust.yml\">\n      <img alt=\"Rust CI\" src=\"https://github.com/aurabx/harmony/actions/workflows/rust.yml/badge.svg\" />\n    </a>\n    <a href=\"https://github.com/aurabx/harmony/actions/workflows/build.yml\">\n      <img alt=\"Builds\" src=\"https://github.com/aurabx/harmony/actions/workflows/build.yml/badge.svg\" />\n    </a>\n  </p>\n</div>\n\n---\n\n<div align=\"center\">\n\n### 🛠️ This project was built by [Aurabox](https://github.com/aurabx)\n\n*Some of our other projects...*\n\n[![Runbeam](https://img.shields.io/badge/Runbeam-Data_Mesh_Platform-purple?style=flat-square)](https://runbeam.io)\n[![JMIX](https://img.shields.io/badge/Aurabox-Medical_Imaging_Exchange-blue?style=flat-square)](https://aurabox.cloud)\n\n</div>\n\n---\n\n## Overview\n\nHarmony 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.\n\nHighlights:\n- Multi-protocol: HTTP/JSON passthrough, FHIR, DICOM/DICOMweb (QIDO-RS/WADO-RS), JMIX\n- Multi-content-type: Automatic parsing of JSON, XML, CSV, form data, multipart, and binary content\n- Configurable pipelines: endpoints + ordered middleware + services/backends\n- Hot configuration reload: zero-downtime updates for most config changes\n- Authentication: JWT (recommend RS256 in production), optional Basic\n- Transformations: JSON transforms (JOLT), DICOM↔DICOMweb bridging, JMIX packaging\n- Runbeam Cloud Integration: Gateway authorization for autonomous API access with 30-day machine tokens\n- Secure Token Storage: Encrypted filesystem storage for machine tokens (no configuration needed)\n- Security: XXE prevention, CSV formula injection mitigation, configurable size limits\n- Operationally sound: structured logging, local ./tmp storage convention\n\nStatus: under active development. For more information, visit https://harmonyproxy.com.\n\n## Who is this for?\n- Platform teams building data meshes or integration hubs (healthcare and beyond)\n- Developers integrating HTTP/JSON services and healthcare protocols (FHIR, DICOM/DICOMweb)\n- Operators who need auditable, configurable request/response pipelines\n\n## Quick start\n\n### Install pre-built binaries\n\nThe fastest way to get started is with pre-built binaries for your platform. Download the latest release from [GitHub Releases](https://github.com/aurabx/harmony/releases/latest).\n\n**Supported platforms:**\n- Linux x86_64 (Ubuntu, Debian, Fedora, RHEL, etc.)\n- Linux ARM64 (ARM64 servers)\n- macOS Intel (x86_64)\n- macOS Apple Silicon (ARM64)\n- Windows x64\n\n#### Linux x86_64\n\n```bash\n# Download the latest release\nwget https://github.com/aurabx/harmony/releases/latest/download/harmony-x86_64-unknown-linux-gnu.tar.gz\n\n# Download and verify SHA256 checksum\nwget https://github.com/aurabx/harmony/releases/latest/download/harmony-x86_64-unknown-linux-gnu.sha256\nsha256sum -c harmony-x86_64-unknown-linux-gnu.sha256\n\n# Extract the archive\ntar xzf harmony-x86_64-unknown-linux-gnu.tar.gz\n\n# Make executable\nchmod +x harmony\n\n# Optional: Move to system path\nsudo mv harmony /usr/local/bin/\n```\n\n#### Linux ARM64\n\n```bash\n# Download the latest release\nwget https://github.com/aurabx/harmony/releases/latest/download/harmony-aarch64-unknown-linux-gnu.tar.gz\n\n# Download and verify SHA256 checksum\nwget https://github.com/aurabx/harmony/releases/latest/download/harmony-aarch64-unknown-linux-gnu.sha256\nsha256sum -c harmony-aarch64-unknown-linux-gnu.sha256\n\n# Extract the archive\ntar xzf harmony-aarch64-unknown-linux-gnu.tar.gz\n\n# Make executable\nchmod +x harmony\n\n# Optional: Move to system path\nsudo mv harmony /usr/local/bin/\n```\n\n#### macOS Intel (x86_64)\n\n```bash\n# Download the latest release\ncurl -LO https://github.com/aurabx/harmony/releases/latest/download/harmony-x86_64-apple-darwin.tar.gz\n\n# Download and verify SHA256 checksum\ncurl -LO https://github.com/aurabx/harmony/releases/latest/download/harmony-x86_64-apple-darwin.sha256\nshasum -a 256 -c harmony-x86_64-apple-darwin.sha256\n\n# Extract the archive\ntar xzf harmony-x86_64-apple-darwin.tar.gz\n\n# Remove quarantine attribute (required on macOS)\nxattr -d com.apple.quarantine harmony\n\n# Make executable (if needed)\nchmod +x harmony\n\n# Optional: Move to system path\nsudo mv harmony /usr/local/bin/\n```\n\n#### macOS Apple Silicon (ARM64)\n\n```bash\n# Download the latest release\ncurl -LO https://github.com/aurabx/harmony/releases/latest/download/harmony-aarch64-apple-darwin.tar.gz\n\n# Download and verify SHA256 checksum\ncurl -LO https://github.com/aurabx/harmony/releases/latest/download/harmony-aarch64-apple-darwin.sha256\nshasum -a 256 -c harmony-aarch64-apple-darwin.sha256\n\n# Extract the archive\ntar xzf harmony-aarch64-apple-darwin.tar.gz\n\n# Remove quarantine attribute (required on macOS)\nxattr -d com.apple.quarantine harmony\n\n# Make executable (if needed)\nchmod +x harmony\n\n# Optional: Move to system path\nsudo mv harmony /usr/local/bin/\n```\n\n#### Windows x64\n\n```powershell\n# Download the latest release (using PowerShell)\nInvoke-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\"\n\n# Download SHA256 checksum\nInvoke-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\"\n\n# Verify checksum\nGet-FileHash -Algorithm SHA256 harmony-x86_64-pc-windows-msvc.tar.gz\n# Compare the output with the contents of the .sha256 file\n\n# Extract the archive (tar is built into Windows 10+)\ntar xzf harmony-x86_64-pc-windows-msvc.tar.gz\n\n# Optional: Add to PATH\n# Move harmony.exe to a directory in your PATH, or add the current directory to PATH\n```\n\n#### Running the binary\n\nOnce installed, run Harmony with a configuration file:\n\n```bash\n# If in current directory\n./harmony --config /path/to/config.toml\n\n# If installed to /usr/local/bin or in PATH\nharmony --config /path/to/config.toml\n```\n\nNote: To use the example configurations, you'll need to clone this repository or download them separately from the [examples directory](https://github.com/aurabx/harmony/tree/main/examples).\n\n---\n\n### Local development\n\nFor contributors who want to build from source:\n\nPrerequisites:\n- Rust (stable) via rustup\n- macOS or Linux\n\nBuild and run with the example configuration:\n\n```bash\n# Build\ncargo build\n\n# Run the basic echo example\ncargo run -- --config examples/basic-echo/config.toml\n```\n\nTry the basic echo endpoint:\n\n```bash\n# In another shell\ncurl -i http://127.0.0.1:8080/echo\n```\n\nIf configured, you should receive an echoed response from the sample backend. Explore more examples under the `examples/` directory (each has its own README).\n\n### Docker\n\n#### Option 1 – Run with Docker Compose (recommended)\n\nFor local development or quick testing:\n\n```bash\n# Build and start containers\ndocker compose up\n\n# Alternatively, to rebuild and restart cleanly\ndocker compose up --build --force-recreate -d\n\n# Test the service\ncurl -i http://localhost:8080/echo\n```\n\nCompose uses the included `Dockerfile.build` so everything builds from source inside Docker—no Rust toolchain required on the host.\n\n**Ports**\n\n* **8080** – Main service endpoints\n* **9090** – Management API (if enabled)\n\n---\n\n#### Option 2 – Build and run manually (from prebuilt or local binaries)\n\nIf you have prebuilt binaries or are running from CI output, use the lean runtime image (`Dockerfile`):\n\n```bash\n# Build image from prebuilt binaries (fast path)\ndocker build -t harmony .\n\n# Run with default config\ndocker run -p 8080:8080 -p 9090:9090 \\\n  -v $(pwd)/config:/etc/harmony:ro \\\n  harmony\n\n# Run with example config\ndocker run -p 8080:8080 \\\n  -v $(pwd)/examples:/examples:ro \\\n  harmony --config /examples/basic-echo/config.toml\n```\n\nIf you'd rather build everything from scratch (no prebuilt binaries), specify the full build image explicitly:\n\n```bash\ndocker build -f Dockerfile.build -t harmony .\ndocker run -p 8080:8080 harmony\n```\n\n---\n\n#### Option 3 – Use the published image\n\nOnce your CI workflow pushes to GHCR:\n\n```bash\ndocker pull ghcr.io/aurabx/harmony:latest\ndocker run -p 8080:8080 -p 9090:9090 ghcr.io/aurabx/harmony:latest\n```\n\n---\n\nThis layout clarifies:\n\n* **Compose / Dockerfile.build** → full source build (developer-friendly)\n* **Dockerfile** → prebuilt-binary runtime (used by CI and GHCR images)\n* **Published image** → fastest start for end-users\n\n\n## Configuration\nHarmony's configuration is file-based (TOML) and can include additional pipeline/transform files from a directory.\n\nExamples (each with README, config, and pipelines):\n- `examples/basic-echo/` - Simple HTTP passthrough\n- `examples/fhir/` - FHIR with authentication\n- `examples/transform/` - JOLT transformations\n- `examples/fhir-to-dicom/` - Protocol translation\n- `examples/jmix/` - JMIX packaging\n- `examples/dicom-backend/` - DICOM SCU operations\n- `examples/dicom-scp/` - DICOM SCP endpoint\n- `examples/dicomweb/` - DICOMweb support\n- `examples/jmix-to-dicom/` - JMIX to DICOM workflow\n\nCore building blocks:\n- Networks: bind addresses/ports and optional WireGuard\n- Endpoints: public-facing routes (HTTP/FHIR/DICOMweb)\n- Middleware: ordered request/response modifiers (e.g., JWT auth, transforms)\n- Services/Backends: where work is performed (e.g., DICOMweb client, echo service)\n- Storage: project-local filesystem path (./tmp by default)\n- Hot-reload: automatic config updates with zero-downtime for most changes\n\nSee [docs/configuration/configuration-file.md](docs/configuration/configuration-file.md), [docs/configuration/endpoints.md](docs/configuration/endpoints.md), [docs/configuration/middleware.md](docs/configuration/middleware.md), and [docs/configuration/backends.md](docs/configuration/backends.md) for details.\n\n## Documentation\n- Docs index: [docs/index.md](docs/index.md)\n- Getting started: [docs/guides/getting-started.md](docs/guides/getting-started.md)\n- Configuration: [docs/configuration/configuration-file.md](docs/configuration/configuration-file.md)\n- Content types: [docs/configuration/content-types.md](docs/configuration/content-types.md) (JSON, XML, CSV, multipart, binary)\n- Endpoints: [docs/configuration/endpoints.md](docs/configuration/endpoints.md)\n- Middleware: [docs/configuration/middleware.md](docs/configuration/middleware.md)\n- Backends: [docs/configuration/backends.md](docs/configuration/backends.md)\n- Router: [docs/architecture/router.md](docs/architecture/router.md)\n- Envelope model: [docs/architecture/envelope.md](docs/architecture/envelope.md)\n- Management API: [docs/api/management-api.md](docs/api/management-api.md) (includes Runbeam Cloud authorization)\n- DIMSE integration: [docs/integrations/dicom-dimse.md](docs/integrations/dicom-dimse.md)\n- Testing: [docs/guides/testing.md](docs/guides/testing.md)\n- Security: [docs/security/overview.md](docs/security/overview.md)\n- System description: [docs/architecture/overview.md](docs/architecture/overview.md)\n\n## System requirements\n- Rust (stable)\n- macOS or Linux runtime environment\n- DCMTK (required for DICOM SCU operations: C-GET and C-MOVE; optional for persistent C-STORE SCP)\n  - macOS (Homebrew): `brew install dcmtk`\n  - Debian/Ubuntu: `sudo apt-get install dcmtk`\n\n## Security\n- JWT: prefer RS256 with strict algorithm enforcement; validate exp/nbf/iat and iss/aud where applicable\n- Encryption: AES-256-GCM with ephemeral public key, IV, and authentication tag encoded in base64\n- Secrets: do not commit secrets; use environment variables or secret managers\n- Temporary files: prefer ./tmp within the working directory\n\n**Environment variables:**\n\n```bash\nexport RUST_LOG=harmony=info                       # overrides logging.log_level\nexport RUNBEAM_ENCRYPTION_KEY=AGE-SECRET-KEY-1...  # encrypts the stored machine token\n./harmony --config config.toml\n```\n\n- [Environment Variables](docs/configuration/environment.md): every variable Harmony reads, with defaults and precedence.\n- [Managing Secrets](docs/security/secrets.md): key generation, rotation, and secret managers.\n- [Encryption Key Management](docs/security/encryption-key-management.md): CLI-managed, environment, auto-generated, and pre-provisioned keys and tokens.\n\n## Contributing\nWe welcome issues and pull requests! Please read [CONTRIBUTING.md](CONTRIBUTING.md) and [DEVELOPER.md](DEVELOPER.md) for workflow and development standards. Our community guidelines are defined in [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).\n\n## License and commercial use\nHarmony Proxy is licensed under the Apache License, Version 2.0.\n\nImportant: 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.\n\n## Support\n- General questions and support: hello@aurabox.cloud\n- Security or conduct concerns: hello@aurabox.cloud\n\n---\n\n<div align=\"center\">\n\n### 🛠️ This project was built by [Aurabox](https://github.com/aurabx)\n\n*Some of our other projects...*\n\n[![Harmony](https://img.shields.io/badge/Harmony-API_Gateway-purple?style=flat-square)](https://github.com/aurabox/harmony-proxy)\n[![Runbeam](https://img.shields.io/badge/Runbeam-Data_Mesh_Platform-purple?style=flat-square)](https://runbeam.io)\n[![JMIX](https://img.shields.io/badge/Aurabox-Medical_Imaging_Exchange-blue?style=flat-square)](https://aurabox.cloud)\n\n</div>\n\n---",
  "bytes": 13755,
  "sha": "32ae367998eb12e5a6dcaf229fb1f75c9e27b5f5916384a570f3358854ed9768",
  "repo_slug": "aurabx/harmony",
  "fonte": "repo",
  "truncated": false,
  "api": "https://api.agentalog.com/api/listings/okf_aurabx_harmony_docs_index_md_b821619a/readme"
}