Medplum Agent

On-prem agent for device connectivity.

Building

Published releases are built using Github Actions. See the build-agent workflow for details.

The following tools are used to build the agent:

• Node.js
• Node.js Single Executable Applications to build the .exe file
• NSIS to build the installer
• Shawl for the Microsoft Windows service wrapper
• Azure Trusted Signing to sign the executable files

Authentication and Signing

The build process uses OpenID Connect (OIDC) to authenticate with Azure Trusted Signing. This provides secure, secret-free authentication using federated credentials.

Required GitHub Secrets

For Azure OIDC Authentication:

• AZURE_TENANT_ID - Azure Active Directory tenant ID
• AZURE_CLIENT_ID - Azure application client ID (from service principal with federated credentials)
• AZURE_SUBSCRIPTION_ID - Azure subscription ID

For GPG Signing:

• MEDPLUM_RELEASE_GPG_KEY - The private GPG key (imported before signing)
• MEDPLUM_RELEASE_GPG_KEY_ID - GPG key identifier
• MEDPLUM_RELEASE_GPG_PASSPHRASE - GPG key passphrase

Setup Instructions

To configure OIDC authentication for Azure Trusted Signing:

1. Create a Microsoft Entra application and service principal
2. Add federated credentials for GitHub Actions
3. Assign the Trusted Signing Certificate Profile Signer role to your service principal
4. Configure the required GitHub secrets

For detailed setup instructions, see Authenticating with OpenID Connect.

References

• Azure Trusted Signing Action
• Azure Trusted Signing with OIDC
• Azure Trusted Signing Documentation
• Shawl
• NSIS

Docker Image

Build and run the docker image

docker build -t medplum-agent:latest \
  --build-arg GIT_SHA=$(git log -1 --format=format:%H) \
  --build-arg MEDPLUM_VERSION=3.0.3 .

docker run --rm \
  -e MEDPLUM_BASE_URL="" \
  -e MEDPLUM_CLIENT_ID="" \
  -e MEDPLUM_CLIENT_SECRET="" \
  -e MEDPLUM_AGENT_ID="" \
  medplum-agent:latest

Optionally set the MEDPLUM_LOG_LEVEL environment variable

  -e MEDPLUM_LOG_LEVEL="DEBUG"