jDeploy Developer Guide

jDeploy provides a graphical user interface that makes it easy to configure your app’s deployment settings such as icons, splash screens, file associations, etc…​ After you’re satisfied with the settings, press "Publish", and it will publish your app so that users can download the latest version.

When you publish your application using jDeploy, your users will instantly be able to download your app at https://www.jdeploy.com/~YOUR-APP-NAME

The download page will present the correct installer for the user’s platform. E.g. if they are on Windows, it will show the Windows installer; if they are on Mac, it will show the Mac installer; and if they are on Linux, it will show the Linux installers.

The user can click "Other platforms…​" to see the installers for other platforms.

The download page includes links for Windows, Mac, and Linux. At time of writing, Linux includes two different download types: .deb, and .tar.gz, but more may be added as there is demand.

The installer that is downloaded from the download page will prompt the user to select relevant installation options, such as whether to add a link in the Dock (Mac only), or the Start Menu (Windows Only), and whether to enable auto-update (default "On").

When an app is already installed, the installer shows Update and Uninstall buttons instead of just "Install", making it clear what action will be taken.

If the app includes AI integrations (such as MCP servers, skills, or agents) and at least one supported AI tool is detected on the system, the installer shows an Install AI Integrations checkbox. Checking it opens a dialog where the user can select which AI tools to configure. See AI Integrations for more information about AI tool integration.

After selecting the desired options, the user can press the Install button, which will trigger the installation of your app. This will only take a second, and, when complete, the user will be prompted with a dialog as follows:

In this example, clicking on the "Open SwingSet2", will open the app as shown below:

When you deploy your app with jDeploy, you don’t need to sign or notarize it as you normally would when deploying a Mac application. jDeploy handles all of this so you don’t need to worry about it. You don’t require any Apple developer certificates; nor do you require an Apple developer account. Mac users running the latest versions of MacOS will be able to download and install your app, by simply downloading it from the jDeploy download page, and running the installer.

If, however, you do have an Apple Developer account, and want to sign and notarize your app, you can do this as well, via a convenient Github action.

jDeploy currently uses Azul’s OpenJDK REST API to download an appropriate JRE, or JDK on demand. You can specify which version of Java your app requires in your jDeploy config file. You can also specify whether your app requires a full JDK, or JavaFX. Deploying JavaFX apps with jDeploy is actually quite painless - as you don’t need to bundle the JavaFX jars or modules with your distribution.

All versions of Java should work. If a new version comes out that isn’t yet in the "drop-down" list of the GUI, you can just enter the version manually in the package.json file.

You can automate your deployments using the jDeploy Github action. Publish your app as a GitHub release, or using npm’s repository.

jDeploy supports hosting your releases on both GitHub (as release artifacts) or npm. When you publish a new version, your app will automatically detect this the next time it is launched, so that you can be sure that your users are always working with your latest version.

The jDeploy GitHub action will allow you to publish native apps that stay in-sync with changes in a particular branch of your repository. When you commit changes to that branch, the app will automatically receive the update the next time it is launched. This all happens through the magic of Github actions.

Download and install the jDeploy desktop application for your platform. macOS, Windows, and Linux are supported.

The jDeploy main menu, shown below, provides 3 main options:

If you already have a jar file (or a project that produces an executable jar file), you should use the "Import Project" option in the main menu to configure jDeploy to deploy your jar file as a native application.

Either enter the path to your project’s directory in the provided text field, or press "Select…​" to select it from a file chooser dialog.

If you intend to use GitHub actions to automatically deploy your application in response to commit and tag events, then you can check the "Generate GitHub Workflow" checkbox. This will generate a basic workflow in the .github/workflows directory.

Once you have selected your project directory, press "Import"

This should open the project editor dialog, as shown below:

This dialog allows you to configure your desktop application. You can configure such things as:

See [project-editor] for more information about the fields and options available in the project editor.

jDeploy does its best to find your app’s main jar file. You should see the path (relative to project root) in the JAR File field. If this is incorrect, or empty, the first thing you’ll want to do is to correct this. Press the "Select…​" button to select the correct jar file.

The name and title fields will also be populated with default values, based on the name of your Jar file. Inspect these and change as desired. The critical fields, for publishing your application, are the Name, Version, Title, and Author fields.

The Name field should be your globally unique project name. If you are publishing to npm, for example, this will be the name of your npm package.

The Title field is the human-readable title of your application. This is what will be displayed in the application menu, and in the installer.

Currently (as of jDeploy 5.0.0), jDeploy supports publishing to the following platforms:

To publish your application, you’ll need to configure the Publish Targets section of the project editor dialog. By default, you’ll find that npm is selected as a publish target. If you don’t want to publish to npm, you can uncheck this option.

To install your application, simply download the installer for your platform from the download page, and run it. The installer will guide you through the installation process.

E.g. On windows, it will download the installer as an exe file. You can run this directly from your browser’s downloads:

On macOS, it will download a .tar.gz file with an .app file inside. You can extract this file and run the .app file to install your application.

Linux provides 3 different options for installation:

Choose the option that is most appropriate for your system.

The vanilla installer UI is shown below. We’ll cover later, how you can customize this to match your app’s branding.

On Windows it provides options to add to the Start menu, as well as adding a desktop shortcut. On macOS it will provide an option to add to the Dock instead of the start menu.

Users can select the auto-update settings that they prefer. Recommended to leave it "On" so that the application will automatically download updates for your application when they are available.

Click the "Install" button to proceed with the installation.

This will prompt you with a confirmation dialog as shown below:

Click "Yes" to proceed with the installation.

Once you have confirmed, the installation will proceed.

If all goes well, you should see a dialog like the one shown below:

Click "Open <Your application name>" to launch your application.

Notice, that the application should also be available via the start menu.

To publish to GitHub releases, you’ll need to generate a personal access token. See the GitHub documentation for details on creating your token. You can use a classic token or a fine-grained token, as long as it has permission to publish releases.

Once you have configured your GitHub repository and generated your personal access token, you can press the "Publish" button in the project editor dialog to publish your application.

In the project editor, click on the "Publish" button in the lower right of the dialog.

This will prompt you to confirm that you want to publish your application.

Click "Yes" to proceed.

Next, you’ll be asked to select the GitHub account you wish to use to publish your application. If you haven’t already configured a GitHub account, you can do so by pressing the "Add Account" button.

If this is your first time publishing, you’ll need to add an account, by pressing "Add a new account". This will open a dialog where you can enter your GitHub username and personal access token.

You can enter anything you like into the "Account Name" field. This is just for you to identify the account. The "Token" field is where you’ll paste the personal access token that you generated in the previous step.

Press "Save" to save the account, and then press "Continue" to proceed with publishing your application.

While publishing, you’ll see a progress dialog like the one shown below:

If all goes well, you should see a dialog like the one shown below:

You can click on "View Download Page" to view the download page for your application. This page will provide a link to download the installer for your application.

If you eschew GUIs and prefer to work on the command-line, the following instructions are for you.

In terminal, navigate to a directory containing an executable .jar file that you would like to publish.

This will generate a package.json file with settings to allow you to publish the app to npm.

The following platforms are currently supported: . windows-arm64 - Windows on ARM64 (e.g. Surface Pro X) . windows-x64 - Windows on x64 (Intel/AMD) . mac-arm64 - Mac on ARM64 (Apple Silicon) . mac-x64 - Mac on x64 (Intel) . mac-high-sierra - A legacy build compatible with MacOS 10.10 to 10.13 . linux-arm64 - Linux on ARM64 (e.g. Raspberry Pi) . linux-x64 - Linux on x64 (Intel/AMD) . debian-arm64 - Debian-based Linux on ARM64 (e.g. Raspberry Pi) . debian-x64 - Debian-based Linux on x64 (Intel/AMD)

To configure your platform-specific bundles, open the project editor for your project, and click on the "Platform-Specific Bundles" tab.

Check the "Enable Platform-specific Bundles" checkbox to enable this feature.

If you are publishing to npm, then you’ll need to specify alternate npm package names for each platform-specific bundle.

Under the hood, these patterns are stored in files whose names start with .jdpignore in the same directory as your package.json file.

The GUI provides a convenient way to edit these files, but you can also edit them directly in your text editor, if you prefer.

See Platform-Specific Bundle Properties for a description of how to configure platform-specific bundles directly in the package.json file.

Such file associations can registered by adding the documentTypes property to the jdeploy object. E.g.

The documentTypes array may contain zero of more object entries, with the following properties:

Since version 5.3, jDeploy allows you to associate your application with directories and folders. This enables users to open entire directories with your application, making it ideal for project-based workflows, IDEs, build tools, and workspace management applications.

When directory associations are configured, users can:

When a user launches your app by opening an associated file type (e.g. by dragging the file on your app icon, or selecting your app in the "Open with" menu), you will likely want to know which file triggered the launch. On Windows and Linux, these file paths are passed as arguments in your main() method. E.g.

On Macintosh, you need to use the java.awt.Desktop class to be notified when the user opens a file with your app.

To add multiple URL schemes, you can simply add multiple values separated by commas in the text field.

e.g.

"myapp,podcast,feed"

In this case the app would respond to URLs like "myapp:…​", "podcast:…​", and "feed:…​"

You can associate your app with both custom schemes, and standard schemes. For a list of standard URL schemes that you might want your app to be able to handle, see this wikipedia entry.

Do this by adding a urlSchemes property of the jdeploy object with an array of string schemes.

E.g.:

With the above configuration in the package.json file, your app would be launched when the user clicks links like "jdtext:…​." in a webpage.

E.g.

When a user launches your app by clicking on a link, you will likely want to know the URL that triggered the launch.

The following describes the legacy approach without singleton mode.

On Windows and Linux, these URLs paths are passed as arguments in your main() method. E.g.

On Macintosh, you need to use the java.awt.Desktop class to be notified when the user opens a URL with your app.

The following table shows the permissions that are currently supported, along with their corresponding Info.plist key on MacOS.

Each permission entry may include the following properties:

jDeploy 5.2 adds support for configuring applications to run with elevated privileges. This is configured using the jdeploy.runAsAdministrator property in package.json.

To enable singleton mode, set "singleton": true in your jdeploy configuration:

You can also enable this in the GUI on the Build tab by checking the "Singleton Application" checkbox.

To receive forwarded files, URIs, and activation events in your running application, you need to add the jdeploy-desktop-lib dependency and register a JDeployOpenHandler.

Singleton mode and jdeploy-desktop-lib enable several powerful integration patterns:

Define CLI commands in the jdeploy.commands section of your package.json:

You can also configure commands in the GUI on the CLI Commands tab.

Your application can detect that it’s running as a CLI command by checking the jdeploy.mode system property:

Since 6.1, applications launched via npm/npx receive jdeploy.mode=npx, allowing you to distinguish between native launcher execution and npm/npx execution. This is useful when certain features (like native launcher-specific capabilities) are not available in npx mode.

Each command entry can include an args array of additional arguments that the launcher passes to your Java main() before any user-supplied arguments. This is useful when you have multiple commands that share the same JAR but need to distinguish which command was invoked:

Commands can implement special behaviors by adding an implements array:

Implementations can be combined. For example:

This gives the command both service management and self-update capabilities.

The launcher implementation is special—it launches your app in GUI mode rather than command mode:

Users can then run:

For a working example, see the jdeploy-hello-commands project, a bare-bones app with a CLI command alongside its GUI.

To make a CLI command work as a service, add service_controller to its implements array:

This adds service lifecycle commands that users can run:

Your Java application just needs to start its server logic and stay alive—the launcher handles all service registration and lifecycle management.

When your application includes services, jDeploy can install a system tray application called the Background Helper. This provides a convenient UI for managing services and accessing quick actions.

For a working example, see the jdeploy-service-example project, a Quarkus REST service deployed with jDeploy as a background service with a system tray helper.

jDeploy itself ships with an MCP server that AI coding agents can use directly. When you install jDeploy, the installer detects which AI tools you have installed (Claude Desktop, Claude Code, VS Code Copilot, Cursor, Codex CLI, Windsurf, Gemini CLI, and others) and lets you choose which ones to integrate with.

Once connected, your AI coding agent can:

For example, in Claude Code you can say:

And the agent will analyze your project, configure the appropriate settings, and guide you through publishing.

You can also register your own application as an MCP server that AI tools discover and use automatically. During installation, jDeploy configures the MCP server in the user’s AI tool configurations.

Beyond MCP servers, jDeploy can also install Claude Code skills and agents. Place them in your project’s jdeploy-bundle/ai/skills/ and jdeploy-bundle/ai/agents/ directories respectively. They are discovered during installation and configured in the user’s Claude Code settings.

For a working example, see the jdeploy-mcp-example project, a Quarkus MCP server deployed with jDeploy.

jDeploy 6.0 ships with its own MCP server that AI coding agents can use directly. When you install jDeploy, the installer detects which AI tools you have installed and lets you choose which ones to integrate with.

Once connected, you can simply ask your AI coding agent to set up jDeploy:

The agent will analyze your project, configure the appropriate settings, set up the GitHub Actions workflow, and guide you through publishing—all without leaving your editor.

See AI Integrations for the full list of supported AI tools and detailed configuration options.

When you import your existing project into jDeploy, it will append instructions to your CLAUDE.md file to help Claude complete the setup. This provides context about your jDeploy configuration that Claude can use when assisting with your project.

The workflow is:

If you’ve already set up jDeploy with your project and want to add Claude integration, the project editor has a menu option for appending (or creating) jDeploy’s instructions to your CLAUDE.md file.

JVM options are options that configure how the JVM works. They are always marked with the "-X" prefix. Some examples of commonly-used JVM options include:

You can set system properties using the -D prefix. E.g. -Dmyapp.setting=foobar

Arguments that are not prefixed with -X or -D are treated as program arguments. They will be passed to your program, and you can receive them in your main(String[] args) method.

jDeploy supports placeholder variables and expressions that can be embedded in your run arguments and configuration file paths. These are replaced with the appropriate values at runtime. Placeholder variables are marked with {{ …​ }}.

In some cases you may want a setting to only be applied on a specific platform. For example some JVM options may be mac specific. jDeploy provides a minimal syntax for marking an argument as platform-specific. For system properties, you would add a condition after the -D prefix, so instead of -Dfoo=bar, you would have -D[CONDITION]foo=bar where CONDITION is one or more platform names ("mac-x64", "mac-arm64", "linux", "win") delimited by pipes. Some examples:

A similar syntax is used for platform-specific JVM options: -X[CONDITION]value, where CONDITION is one or more platform names ("mac-x64", "mac-arm64", "linux", "win") delimited by pipes. Some examples:

Finally, for program arguments (i.e. arguments that are passed to your main(args) method), you can mark them as platform-specific by adding a -[CONDITION] prefix. E.g. -[mac]anArgOnlyAddedOnMac. Some more examples:

Since version 5.2.3, applications can configure file descriptor limits on Unix-like systems (macOS and Linux) using the -Djdeploy.file.limit system property. This is useful for applications that need to open many files or network connections simultaneously.

Since version 5.2, jDeploy supports loading additional runtime arguments from external JSON configuration files. This allows environment-specific configuration without repackaging the application.

jDeploy 6.0 injects a comprehensive set of system properties into the JVM that your application can use to detect its runtime environment:

Example usage:

See CLI Commands for more information about mode detection and multi-modal applications.

To publish your packages on GitHub, you’ll need to add the following to your workflow.

This should be placed in a step after you have built your app already (e.g. using maven, gradle, ant, etc…​).

If this action is used in a workflow on a branch push, then it will publish artifacts on a release named after the branch that the workflow is running on. We recommend configuring your workflow to only trigger on branches ending in -snapshot (e.g. main-snapshot) and tags beginning with v (e.g. v1.0.0) to avoid creating unwanted tags like "main".

If this action is used in a workflow on a tag push, then it will add the app bundles as artifacts directly on the release/tag in GitHub.

The URL convention for the jDeploy download page for apps hosted on GitHub is:

E.g. The SwingSet app whose repository is located at https://github.com/shannah/swingset2, will have download page at https://www.jdeploy.com/gh/shannah/swingset2.

To access the download page for a specific branch you can append the branch name to the URL. E.g. The download for the "Swing Set 2 (master)" app, which is synchronized with the "master" branch, the URL would be:

By default, MacOS apps are distributed as an installer, which is signed and notarized by jDeploy, so you don’t need to sign it with your own Apple developer certificate. However, if you would prefer to sign the app with your own certificate, you can distribute it as a DMG instead of an installer, you can do this via the jDeploy DMG GitHub action.

The IntelliJ plugin project templates include a DMG job in the GitHub workflow by default, but you do need to define a configuration variable and some secrets in your repository.

For full instructions, see the README.

See: Example release produced by this action.

Your release artifacts must be published to a public repository in order for the jDeploy installer to be able to download updates for your app. If your repository is private, you can publish your releases in a different repository which is public.

Step One: Create a Public Repository for your Releases

For example, consider a scenario where your app is in the private repository yourname/yourapp. Then you could create a new public repository at yourname/yourapp-releases.

Step Two: Create a Personal Access Token

In order to publish releases to a different repository, you’ll need to create a personal access token that has permission to create releases in the other repository.

Learn more about personal access tokens.

Once you’ve created the personal access token, you’ll need to add it as a secret in your repository.

Step Three: Specify the target_repository in your workflow

Finally, you’ll need to modify the invocation of the jdeploy GitHub action to use the target_repository parameter, and change the github_token parameter to use your personal access token instead of the default github_token.

The next time your run the workflow, it should publish the releases to the yourapp-releases repository instead of the yourapp repository.

This action will add (and update) a tag named "jdeploy" to your repo, with a file named "package-info.json". This tag must not be deleted. The package-info.json file is used by both the jDeploy launcher and installer obtain details about your app, so that it knows what versions are available.

If you’re starting out with a new JavaFX project, then the jdeploy-javafx-starter may be what you’re looking for. It provides you with a bare-bones JavaFX maven project, based on the official openjfx javafx-archetype-simple archetype, but it comes loaded with a GitHub workflow to auto-generate native installers for all branches and releases.

Getting started is as simple as pressing "Use this template", and you’ll be all set.

See https://github.com/shannah/jdeploy-javafx-starter for details.

The two most common strategies to produce executable jars in Maven are using either a combination of the maven-dependency-plugin and the maven-jar-plugin, or using the maven-assembly-plugin. The latter approach (maven-assembly-plugin) can generate a single "fat" jar with all of your dependencies. The former approach (maven-dependency-plugin and maven-jar-plugin) places your dependencies in a "libs" directory.

By default, jDeploy installs Windows applications to %USERPROFILE%\.jdeploy\apps. Some antivirus software, particularly Windows Defender, may flag executables running from hidden directories (directories starting with .) as potentially suspicious.

To avoid these warnings, you can use the winAppDir property to specify a different installation directory:

The value is relative to %USERPROFILE%. In this example, the app would be installed to %USERPROFILE%\AppData\Local\Programs instead of %USERPROFILE%\.jdeploy\apps.

Given an application with package name "myapp" and title "My App", the following file structure will be created on Windows:

If the app uses Java 8:

If the app uses Java 11 or higher:

The layout for apps deployed via GitHub releases is slightly different. The main difference is that the app is installed in a directory that is named after the hash of the app’s package name and version. This is to ensure that multiple versions of the same app can be installed side-by-side. Each app has a unique hash prefix that is derived from the package name and version of the app. This hash prefix is used to create a unique directory for the app. In addition, the package is installed in the %HOMEPATH%/.jdeploy/gh-packages directory, rather than the %HOMEPATH%/.jdeploy/packages directory.

If the app uses Java 8:

If the app uses Java 11 or higher:

jDeploy can be installed globally using npm:

To verify the installation:

jDeploy respects the following environment variables:

A typical command-line workflow might look like this:

The following templates are available by default:

Project templates use placeholder variables that are automatically replaced when creating a new project. The available placeholders are:

You can contribute your own project templates to the jDeploy community by submitting them to the jdeploy-project-templates repository.

A typical project template includes:

To use a project template:

The template system will:

When creating templates: