@medplum/agent

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:

• Create a Microsoft Entra application and service principal
• Add federated credentials for GitHub Actions
• Assign the Trusted Signing Certificate Profile Signer role to your service principal
• 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"