From Vassal

How to run VASSAL on Android


A bit of background first.

  • Android is an operating system built on top of the Linux kernel.
  • Android apps are typically written in the Java programming language and executed in Android Run-Time environment (ART).
    • This Android-specific run-time environment is not a real Java Runtime Environment (JRE), and regular Java apps, in particular Graphical User Interface (GUI) Java apps cannot be executed by ART.
  • VASSAL is a Java application, and uses the Java GUI services.
  • The VASSAL app is executed in a Java Run-time Environment (JRE).
    • Java apps do not run directly on the metal, but are run through the JRE abstraction layer. This means a Java app, once build, can run on any system that can run the JRE.
    • VASSAL requires a true JRE, and the ARE is not a real JRE, and VASSAL can therefore not be run directly on Android.

Thus, to run VASSAL on an Android device, we need to get a true JRE onto the device.

We will do that via the very powerful app Termux. Remember, Android runs on a Linux kernel, and we can therefore set up an environment which uses the Linux kernel and run regular Linux user-land applications and services there.

To get a Graphical User Interface (GUI), we need a few more things too. The GUI back-end of Linux is X (nothing to do with what was known as Twitter, even though that service has appropriate the X name and logo). Android does not provide the X service, but we can set that service up in our Termux environment. But that is only half the story. We also need to have an X client that can actually show the GUI to us, and allow us to interact with the applications running on the server. Fortunately for us, X implementations speak the Virtual Network Computing (VNC) language, and we can thus use any of the available VNC apps available for regular Android.

With these considerations clear, we can go onto the practical steps needed to get VASSAL running on an Android device.


Needed apps

For our set-up we need the following Android apps

Below we will go through the steps of setting these up.


Command listed below must be typed into Termux exactly how they are written. Case matters, as in downloads and Downloads are not the same thing. For example, if the instructions tells you to write

pkg update
pkg upgrade

then two commands should be entered exactly as written above at the command prompt. That is first, type p k g [space] u p d a t e [enter] and then p k g [space] u p g r a d e [enter].

If you are reading this on your Android device, you can highlight the commands and copy them to your clipboard. In Termux you can then long-press anywhere and select Paste to paste in the command into the commmand prompt.

Install Termux

Follow the installation instructions on the Termux web-site.

Note There is a Termux app in the Google Play store - do not use that. Currently (2024 and for the past 3+ years), that app is not kept up to date.

If you install from GitHub, be sure to take the version appropriate for you device architecture. If you are unsure, or do not know what your device’s architecture is, take the termux-app_v*+github-debug_universal.apk app.

Whether you install from GitHub or F-Droid you will need to OK installation from “untrusted” sources. Please see this guide.

Once you have installed the Termux app, go a head and launch it as any other app on your device. You will be created by black screen with text on it. Take a minute to read the text. More information, including a “Getting Started” Guide is available at the Termux Wiki pages.

Give Termux access to Android file system

After these two commands have finish, we will set-up Termux to have access to the regular device file system


This is kinda important so that we can use our regular Android browser to download VASSAL modules and they become available inside Termux environment.

Optionally, install Termux:Widget app

To able to launch VASSAL directly from the home screen of your device, you need to install the Termux:Widget Android app. Please follow the installation instructions. As for Termux, do not install the app from the Google Play store.

Install a VNC client

Pick any VNC client you like form the Google Play store (I chose RealVNC). Open up the app, and go past any introduction screens.

About choosing a VNC client

Your choice of VNC client largely determines your experience with VASSAL on your device. It is therefore worth a little effort to look around for the client that will best suit your needs. For VASSAL, you want the client to have a good mouse emulation and perhaps an improved on-screen keyboard. If the VNC client supports physical keyboard and mouse connected to the device (f.ex. via Bluetooth), then that is also attractive.

The Quick (but experimental) Way

This is an experimental way to get you set-up with VASSAL on an Android device. No Warranty!

  • Start up Termux
  • In the terminal type
wget -O
chmod a+x
  • Follow the on-screen instructions

The script Media:Setup-vassal-sh.txt basically does the step below. If you have problems with it, open a thread in the Technical Support & Bugs Forum.

The steps in detail

If the quick (but experimental) way above didn't work, you can follow the steps outlined below

Download VASSAL

Open your regular Android browser and go to 

and select Download VASSAL. Be sure to take the Linux version.

This will put a file a la


in your normal Download folder (adjust the version number to the version you downloaded).


Previously, we made sure that we can see the regular Android file system in Termux, so we can unpack VASSAL into our Termux environment directly from the Android file system. In the command prompt execute

tar -xjvf /sdcard/Download/VASSAL-3.7.9-linux.tar.bz2

Adjust the version number to the version you downloaded. To see which files you have in your Android Download folder, do

ls /sdcard/Download/

After unpacking, you will now have the directory


in your Termux environment (adjust the version number to the version you got). Below, we will assume that we can find the most recent VASSAL version installed in VASSAL-current, so you should make a symbolic link from your unpacked VASSAL installation to that

ln -s VASSAL-3.7.9 VASSAL-current

More on how to upgrade VASSAL below.

Upgrade Termux packages

Termux has many add-on packages that can be installed inside Termux. Let us go a head and upgrade any of these that need upgrading:

pkg update 
pkg upgrade 

Install the Java Runtime Environment in Termux

At the command prompt enter

pkg install openjdk-17-x which nano

After this, you have the JRE that we need for VASSAL installed, plus some utilities you need.

  • openjdk-17-x is the JRE version 17 (adjust for availability)
  • which is small to that finds commands
  • nano is a simple text editor

Actually, openjdk-17-x is the Java Development Kit (JDK), which includes a JRE. But it also has tools for developing Java applications. That is, you have installed a Java development environment on your device.

Get X in Termux

Please also refer to these guidelines for more information.

In the Termux command line type

pkg install x11-repo 

to add a repository of X packages. Then do

pkg install tigervnc xfce4 netsurf

to install a VNC server (tigervnc), a full desktop environment (xfce4), and a simple web-browser (netsurf).


One of the powers of Linux and other open-source platforms, such as Android, is that you have the option to chose what environment you want. As described in the Termux GUI guide you have a variety of options to chose from, and each open can be configured in a variety of ways.

Set-up the graphical environment

In your Termux app do

mkdir -p ~/.vnc 
nano ~/.vnc/xstartup

The first command creates the directory .vnc in your home directory, and the second edits the (new) file xstartup in that directory using the editor nano. In nano put in the lines

xfce4-session &

The lines must be typed exactly as shown above. Then type [ctrl]-x, followed by y and [return] to save the file and close nano. See also Media:Dot-vnc-xstartup.txt (remember to remove first, empty line, and make it executable). Finally, make the script executable

chmod a+x ~/.vnc/xstartup

Next, we will configure our VNC server. Do

nano ~/.vnc/config

to make a new configuration file for our VNC server. In nano type in the exact lines

# Configuration of tigervnc 
# See also

and then [ctrl]-x followed by y, and then [enter] to save the file and quit nano. See also Media:Dot-vnc-config.txt.

Note that the argument to geometry defines the resolution of the graphical interface. You should adjust that to suit your device. Search the World-Wide-Web to find out which resolutions your device supports. If in doubt, fall back to something like 1024x768.

The localhost setting above means that only clients on the same device may connect to the server, thus limiting the risk of malicious "guests" to your device.

You can adjust menu settings of the VNC server in the ~/.vnc/config file. Please refer to the TigerVNC documentation for more.

Launch the graphical environment

In your Termux app, execute

vncserver :1 

The first time you execute this command, you will be prompted to set a password. Please pick a password that you can remember, but do not be too lax about it (i.e., do not make a password like 123456), as up-to-no-good people can get full access to your device through the VNC server. Typically, VNC clients will allow you to store passwords for your connections, or can use some password wallet service to store them. Thus, you do not necessarily need to be able to remember this password indefinitely.

Change VNC password

If you want to change or reset the VNC password, do


and set a new password.

Start the VNC client

Open the regular Android VNC client app you installed, skipping past any introductory screens.

Next, create a new connection. Here, you should use

  • Host: localhost
  • Number: 1 (see more below)
  • Password: The password you created above.

With respect to the number: - The VNC server you started above is listening on port 5901.

  • Some VNC clients expects you to enter the full port number, in which case you must put 5901 as the number.
  • Other VNC clients (e.g., RealVNC) expects you to put the offset relative to the base port 5900, in which case you must put 1 as the number.

Now open the connection. You should see a Linux desktop. How you interact with the desktop depends on the VNC client. The VNC client app typically has a short introduction that allows you to get familiar with the interface.

Alternatively, you may start the VNC client from Termux with

termux-url-open vnc://localhost:5901

to launch your default VNC client.


Now we are ready to actually launch VASSAL.

Go back to your VNC client which should still be running its connection to Termux. If not, then restart the connection from the VNC client app.

Click the Applications menu in the top-left corner and select Terminal Emulator. This will open up a terminal window with a command prompt, similar to what you have in the Termux app.

In that command prompt, type

cd VASSAL-current

to change directory into the VASSAL installation directory. Now type


to start VASSAL. Et voilá, you have VASSAL running on your Android device.

Use the VASSAL application to find your VASSAL modules and open them as you would on a computer.

Stopping the VNC server

Once you are done using VASSAL, you should stop the VNC server. In the Termux app execute

vncserver -kill :1 

to stop the VNC server. The VNC client will be disconnected automatically and you can close that app too

Getting VASSAL modules

To get your favourite VASSAL module, visit

with your regular Android Web-browser, and download the module to your Android Download folder. For example, I took a version of the Gettysburg (125th Anniversary Edition) module (1.2-ch), which gave me the file 

in my Android Download folder. Note that Google Chrome appends the .zip to the file name - it doesn’t actually put the file into a ZIP archive.

You should move the VASSAL modules to your Termux enviroment. Go back to the Termux app, and do for example

cd /sdcard/Downloads/ 
mv GettysburgSmithsonian-1.2.vmod

to remove the .zipfrom the file name. Here cd means "change directory" and mv means "move".

Then, go back “Home” in Termux


and make a directory to hold your VASSAL modules, named for example VMods.

mkdir VMods 

Here, mkdir means "make directory".

We can then move our module there to that we have all our modules in a meaningful place

mv /sdcard/Download/GettysburgSmithsonian-1.2.vmod VMods/


First, open up your Termux app and run the command

vncserver :1 

Then open your VNC client app and reconnect to host=localhost and number=1 and described above. Many VNC client apps lets you save connection settings and you should be able to use that setting to quickly get back.

Upgrading VASSAL

If you want or need to upgrade your VASSAL installation, you should essentially follow the relevant steps above. That is

  • From your regular Android browser, navigate to the VASSAL site and download the VASSAL version for Linux that you need - say VASSAL-3.7.10-linux.tar.bz2
  • Open your Termux app
  • Unpack the downloaded VASSAL archive
tar -xjvf /sdcard/Download/VASSAL-3.7.10-linux.tar.bz2
  • Remove the old current link
rm VASSAL-current
  • Make the newly unpacked installation the current one
ln -s VASSAL-3.7.10 VASSAL-current
  • You may want to delete the old (say 3.7.9) installation to free up some space
rm -rf VASSAL-3.7.9

Upgrade Termux packages

From time to time, you should upgrade the packages installed inside Termux. Do

pkg update 
pkg upgrade


Below are some tricks to get more out of your installation. If the quick (but experimental) way of setting up VASSAL worked for you, then these steps are more or less done already.

VNC Server script

You may want to make a small script to easily start and stop the VNC server. In the Termux app, do

nano vnc 

to make the new file vnc and put in the exact lines below


while test $# -gt 0 ; do
    case $1 in
    start|stop) oper=$1 ;;
    --) break ;;
    *) echo "Usage: $0 [start|stop]"; exit 0;;
case $oper in
    vncserver :1
    vncserver -kill :1

and type [ctrl]-x followed by y and [enter] to save the file and exit nano.

We need to make the script executable, so do

chmod a+x vnc

You can now do

./vnc start 

to start the VNC server, and

./vnc stop 

to stop the VNC server.

You can start the VNC client from within Termux with the command

termux-url-open vnc://localhost:5901

Desktop launcher

To make a Desktop launcher icon for VASSAL in the Termux GUI, do in your Termux app

cd ~/Desktop 
nano VASSAL.desktop 

and enter the exact lines below

[Desktop Entry]

[Desktop Action Run]
Exec=/data/data/com.termux/files/home/VASSAL-current/ -l %f
[Desktop Action Edit]
Exec=/data/data/com.termux/files/home/VASSAL-current/ -e %f

and type [ctrl]-x, followed by y and [enter] to save the file. See also Media:Desktop-VASSAL-desktop.txt (remember to make it executable). Now do

chmod a+x Desktop/vassal.desktop

to make the file executable. You can now double-click the Termux GUI Desktop VASSAL icon to launch VASSAL.

Associate .vmod and .vlog files with VASSAL

In your Termux app, do

mkdir ~/.local/share/mime/packages
nano ~/.local/share/mime/packages/application-x-vassal.xml

and enter the exact line

<?xml version="1.0"?>
<mime-info xmlns=''>
   <mime-type type="application/x-vassal-module">
     <comment>VASSAL module file</comment>
     <glob pattern="*.vmod"/>
   <mime-type type="application/x-vassal-log">
     <comment>VASSAL log file</comment>
     <glob pattern="*.vlog"/>
   <mime-type type="application/x-vassal-save">
     <comment>VASSAL save file</comment>
     <glob pattern="*.vsav"/>

and type [ctrl]-x followed by y and [enter] to save the file and exit nano. See also Media:Dot-local-share-mime-packages-application-x-vassal-xml.txt (remove first, empty line).

Then copy the desktop file to ~/.local/share/applications

mkdir -p ~/.local/share/applications
cp ~/Desktop/VASSAL.desktop ~/.local/share/applications/

Now, update the Application and Mime type data base

update-desktop-database ~/.local/share/applications 
update-mime-database ~/.local/share/mime

Now, double-tapping a .vmod file in the Termux GUI file manager will open up that module in VASSAL.

Download modules in the Termux GUI

In the VNC client connection to your Termux environment, open a terminal as described above and type


This will open a simple web-browser, which you can then direct to

to find the module you want. By default, the modules are downloaded to your Termux home directory. You can move them to your VMods directory by typing in the terminal

mv ~/DDaySmithsonian-2.0.vmod ~/VMods/

for example.

Launch VASSAL from the Android home screen

For this to work, you need to install the Termux:Widget Android app. Please follow the installation instructions. As for Termux, do not install the app from the Google Play store.

Next, open up your Termux app and do

mkdir -p ~/.shortcuts

to make a directory for Termux home screen short cuts. We will make a short cut script named VASSAL in that directory. In the Termux app execute

nano ~/.shortcuts/VASSAL

to open the (new) file ~/.shortcuts/VASSAL in the nano editor. Type in the exact lines below



read -n 1 -p "Do want to start? (Y/n) "
case x$REPLY in
  xy|xY|x) oper=start ;;
  *) oper=stop ;;

case $oper in
    echo "IMPORTANT: Enable Termux Wake-Lock through its notification"
    if test $? -ne 0 ; then 
        read -n 1 -p "Failed to aquire Wake-lock, exiting"
        exit 1

    vncserver \
        -xstartup $xstart \
        -autokill \
        -fg \
        :1 &


    termux-open-url vnc://localhost:5901

    wait $vnc_pid

    echo "Stopping the VNC server"
    vncserver -clean -kill :1

Press [ctrl]-x, followed by y and [enter] to save the script and exit nano. See also Media:Dot-shortcuts-VASSAL.txt (remove first, empty line and remember to make it executable).

This script will be executed from the Termux widget, so we need to make it executable

chmod a+x ~/.shortcuts/VASSAL

Next, we will make a special X start-up script that will execute VASSAL in the GUI session. Do

nano ~/.vnc/xvassal

and put in the exact lines


xfce4-session &
env bash $HOME/VASSAL-current/

followed by [ctrl]-x, followed by y and [enter] to save the script and exit nano. See also Media:Dot-vnc-xvassal.txt (remove first, empty line and remember to make it executable), this script will be executed by the VNC server, so we need to make it executable

chmod a+x ~/.vnc/xvassal

Now we need to add the widget to the Android home screen. Go back to the Android home screen and long-press the background. In the pop-up menu, select Widgets and scroll down to find Termux:Widget. Long press it, and drag to the Home screen.

You will see a small widget (default 2x2) with a list of Termux short-cuts - in particular the short cut VASSAL. You can click that to launch the VNC server and client in one go and have VASSAL running in the Termux GUI environment.


VASSAL running in the Termux GUI


Running my version of the Gettysburg (125th Anniversary Edition) module (1.2-ch).


Files for download

Below are downloadable versions of the scripts generated above. Remember to make them executable

chmod a+x file-name

replacing file-name with the actual file name.

Note, in some of these files (those with remove first line), an additional extra blank line (possibly starting with #) was added at the top of the file. This is because MediaWiki does not allow uploads of shell scripts. Remove that line from the files for example using the editor nano.

Below are links to other files