Voyant Server

VoyantServer is a version of the Voyant Tools server that can be downloaded and run locally. This allows you to do your text analysis on your own computer. It means:

  • You can keep your texts confidential as they will not be cached on our server.
  • You can restart the server if it slows down or crashes.
  • You can handle larger texts without the connection timing out.
  • You can work offline (without an Internet connection).
  • You can have a group of users (like in a workshop or class) run their own instance without encountering load issues on our server.

This document outlines how to download, run and control the server. As this is the first version of the server we expect there to be issues. We have documented some and hope you will share others with us.

Downloading VoyantServer

To download VoyantServer go to the latest releases page and click on the VoyantServer. zip file to download it (this is a large file of about 200MB – it includes large data models for language processing). This is a .zip archive file that needs to be decompressed to be useful.

  • Mac: On the Mac you just double click the file and the OS will decompress it.
  • Windows: In Windows it’s best to right-click on the file and choose a destination directory – it may not work properly if extracted into a virtual directory.
  • Linux: Um, you don’t really need our help for this, right? 🙂

Once you decompress the .ZIP file you should see something like the following:

  • _app: this is the actual web application – you shouldn’t need to view this folder’s contents
  • License.txt: this is the license for the VoyantServer
  • META-INF: this is a part of the VoyantServer architecture – you shouldn’t need to view this folder’s contents
  • README.md: this includes some of the same documentation as on this page
  • server-settings.txt: this is an advanced way to set server options including the port and memory defaults
  • VoyantServer.jar: this is the most important file, the one you’ll click to start the server

Running VoyantServer

Mac OpenTo run the server you need to run the VoyantServer.jar Java JAR file. This Java Archive file is a package with all the resources needed to run the server (including an embedded JETTY server). To run this you need to have Java installed.

  • Mac: You should right-click (control-click) on the VoyantServer.jar file and choose Open from the menu, then you will need to click on Open in the next dialog (which isn’t the default button).
  • Windows: You should be able to simply click on the VoyantServer.jar file.
  • Command-line: It should also be possible to launch the application from the command-line if you’re at the prompt in the same folder as the jar file: java -jar VoyantServer.jar

Once you run VoyantServer you will see a control panel like this: 

Voyant Server Panel

Typically VoyantServer will also automatically launch your browser with the Voyant Tools home screen where you can define a text and get started.

Voyant Tools

Controlling Voyant Server

Voyant Server LabelsFrom the VoyantServer control panel you can:

(1) Stop Server / Start Server: This button’s label will depend on the state of the server – it will be disabled if in the process of starting up the server, it will say Stop Server if the server is already running and Start Server if it isn’t. You can stop the server if it doesn’t seem to be behaving and then restart it. Note: You should always Stop Server to properly release resources when Exiting (Quitting) the VoyantServer. Otherwise re-launching the server may not work.

(2) Open Web: You can open your default web browser with the Voyant Tools entry page that connects with this server. By default, the URL will be You can always connect with a local server by typing this into the Location field of your browser if the browser launched is not the one you want to use.

(2) File -> Exit: You can quit the VoyantServer application (this also terminates the server, though quitting the application without using Exit won’t).

(3) Help: You can access the help page for the VoyantServer from the Help menu.

(4) Port: You can change the port that is used by the server (the default is port 8888). Normally this won’t need to be changed – it’s not recommended to make changes here unless you need to and know what you’re doing. If the port specified is already in use, you can try a slightly different one, 8889 for instance.

(5) Memory: You can increase the memory (in megabytes) allocated to the VoyantServer if you are analyzing larger texts. Make sure you stop and restart the server for the new memory setting to take effect. The default is 1024 (MB).


Server Won’t Start: If you start and stop the server by quitting the VoyantServer app you may get a message that reads:

Port#8888 appears to be in use already

The server in this case is running. But it can be hard to stop and restart. One option is to change the port (to, say 8889) and launch another server – but each time you launch a new server more memory is being used. Another option is to restart your computer – that will clear existing processes. If you know what you’re doing, you can also use the command line to find the process and kill it:

ps aux | grep jetty
kill -9 [process id]

Kill Jetty

Please let us know if you encounter other issues with VoyantServer.

There are also some issues with Voyant Tools, including problems with the Lava, Mandala, and Termometer tools and the Builder skin (among others).