Application Mode
When launching Deephaven, you may want to initialize the server state before any client connects to the server. Application Mode enables users to bind tables, plots, functions, and other objects to named fields that clients can open while the server runs. Deephaven calls these named fields exported fields.
A script application can also bind objects to REPL variables.
Exported fields appear in the IDE under the Panels menu. Use fields to share tables, plots, and other objects that clients can open. To make helper functions callable from queries, bind them to the query scope instead.
Each application is described by an *.app file. The Syntax section lists the keys in these files, for reference.
This guide shows how to create a script application that exports tables to the IDE, and summarizes the other application types and the server settings that control them. To package scripts into a Docker image, see How to use Application Mode scripts. For Application Mode libraries, see How to use Application Mode libraries.
Application types
There are many different applications that you can run, from a Python or Groovy script designed to run in Deephaven, to a dynamic application written in any JVM-based language.
- Script application (
type=script): Run a Python or Groovy script when the server starts. See the Script application example. - Static application (
type=static): Configure an application that declares all of its fields when the server creates the application. Use it when all fields are known and accessible at all times. See Static applications. - Dynamic application (
type=dynamic): Configure an application whose exported fields can change over its lifetime. Use it when fields might be created or removed over time, or as data changes. See Dynamic applications.
Script application example
In this example, we seed the files needed to use Application Mode, start the Deephaven server, and then see the results in the server log and the IDE. This example assumes you run Deephaven with Docker Compose, using the ./data volume from Deephaven's examples.
Note
The Docker Compose files in Deephaven's examples mount ./data in the local deployment directory to /data in the running Deephaven containers. See our guide on Docker bind mounts for more information.
Create an app.d folder inside your ./data directory:
The server reads all files with an .app extension in the app.d folder and executes each one individually in alphabetical order.
As an example .app file, create the file firstApp.app with the following contents.
This application file runs the script named in the file_ line. For this example, the script is firstApp.py, in the same directory as the application file. The script is:
In our "hello world" example, we get the application state through the get_app_state function. ApplicationState collects the state of each application. The last line passes that state to start, so the server runs start when it loads this file.
Setting a field on the provided ApplicationState exports it to connecting clients, as described in the introduction.
Each application has its own state that it can manipulate. This enables similar applications to co-exist without stepping on one another.
In this example, we have one method (start) that runs when the container starts. Inside this method, we set two fields:
- An empty table.
- A time table that updates every second.
Note
Script applications may directly manipulate variables bound in the REPL in addition to, or instead of, using the ApplicationState portion of the Application Mode API.
Once you have these two files inside the app.d directory, configure the server to find them.
Note
The server image uses Python by default, so you don't need to set deephaven.console.type. Set runtime flags in START_OPTS in your docker-compose.yml. See Runtime JVM flags.
Before you start the containers, tell the server where to find the app.d folder, as described in Runtime JVM flags. Add -Ddeephaven.application.dir=/data/app.d to START_OPTS in your docker-compose.yml:
Inside your Deephaven directory, start the containers with docker compose up.
In the server log at startup, you see two exported fields, one for each field the script sets.

Launch the Deephaven IDE in your web browser. Open the Panels menu to see the defined tables hello and world.

Multiple script application example
The Script application example defines the tables hello and world in firstApp.py. A second script can use those tables, and it can make them available in the IDE by assigning them to the query scope.
Here we add to the .app file to run another script:
The fields that firstApp.py sets through ApplicationState are available to secondApp.py through app["world"], as the example below shows. Here we keep file_0 the same, and add a file_1 defined as:
Declaring my_new_table with global makes it a module-level variable, which the script session adds to the query scope. The other tables are only available in the Panels menu. If you want to perform queries on fields defined in Application Mode, you must explicitly assign them to the query scope inside the applications.
Files run in numerical order (after removing the prefix file_), not in the order listed in the application. Because of this, an early file can initialize values that later files use.
Runtime JVM flags
The following flags are available for configuration:
-Ddeephaven.application.dir=/path/to/application/root— The Deephaven server loads all*.appfiles in alphabetical order from the given directory during initialization, before it begins to listen for requests from connecting clients.- If this property is not set, the server uses the
app.ddirectory inside its configuration directory, if one exists.
- If this property is not set, the server uses the
-Ddeephaven.console.type=$SCRIPT_LANGUAGE_TYPE— Specifies which language type the Deephaven server uses for Application Mode and console REPL sessions. The default ispython. The server supports one script type per instance, so every script application must match this value.-Ddeephaven.console.disable=$BOOLEAN— Prevents API clients, including Deephaven's web client, from starting REPL sessions. The default isfalse.
Warning
A REPL session gives its user the same privileges on the host machine as the user running the server process.
Syntax
Deephaven expects the following keys to be in an *.app file:
type— Required. One ofscript,static, ordynamic.scriptType— Required forscriptapplications:pythonorgroovy.enabled— Set totrueorfalseto run or skip the scripts in the application file. The default istrue.id— Required forscriptapplications. An identifier shown only to API clients, which refer to an application byid.name— Required forscriptapplications. The label that users see for this application. Changingnamedoes not affect saved layouts, because clients refer to the application byid.file_N— Required forscriptapplications. Set at least one. Path to each script to run.class— Required forstaticanddynamicapplications: the fully qualified name of the factory class.
Warning
The Deephaven server supports only one script type per instance. If you attempt to load the wrong type of script application, then the server fails fast to aid in debugging the misconfiguration. See deephaven-core#1172 for more details.
The Application Mode configuration reference documents each script key in more detail, including the default for enabled.
Static and dynamic applications
Besides script applications, Deephaven supports static and dynamic applications. You write these in a JVM-based language such as Java, Scala, or Kotlin, and then export them to clients, such as the IDE's Panels menu. Be sure to package these into a jar file and provide them as third-party dependencies to Deephaven's server. See How to install and use Java packages for more information.
Static applications
Static applications define all their fields when the server creates the application.
Implement io.deephaven.appmode.Application.Factory. Its create method returns an Application with its id, name, and fields.
The .app configuration file is as follows:
Dynamic applications
Dynamic applications can create and remove fields while the server runs.
Implement io.deephaven.appmode.ApplicationState.Factory. Its create(listener) method returns an ApplicationState you can add fields to and remove fields from over time.
The .app configuration file is as follows:
Related documentation
- Docker bind mounts
- How to install and use Java packages
- How to use Application Mode libraries
- How to use Application Mode scripts
- Query scope
- Application Mode configuration reference
empty_tabletime_tableupdatedeephaven.appmodePydocget_app_statePydocApplicationJavadocApplicationState.FactoryJavadoc- How to use Application Mode video
Hands-free. Production-ready.