Installing the KSL Applications

Complete before the first class activity on the KSL applications

Author

Manuel D. Rossetti, PhD P.E.

What you are installing, and why

Until now you have used the KSL as a library: you write Kotlin in IntelliJ, and Gradle downloads the KSL for your program to use. The class activities use the KSL applications. These are desktop programs that run a model, compare scenarios, and fit distributions to data without your writing any code. The suite also includes the KSL Server, which lets an AI coding assistant run models and search the textbook for you.

The applications are a separate install from your KSL projects. Nothing in this guide changes your projects or your code.

Plan on about 20 minutes. Do it before class. If you get stuck, follow the troubleshooting section at the end, and if that does not fix it, come to class 10 minutes early with your laptop. Bring the exact error message.

You will do five steps:

  1. Open a terminal.
  2. Check that the terminal can find Java 21.
  3. Run the installer.
  4. Run one model in the KSL Single application.
  5. Start the KSL Server and open its console.

Step 6, connecting an AI coding assistant, is optional.

Step 1. Open a terminal

A terminal is a window where you type commands instead of clicking. You need one for Steps 2 and 3 only.

macOS. Press Command + Space, type Terminal, and press Return.

Windows. Click Start, type PowerShell, and click Windows PowerShell. Do not choose “Run as administrator”; the installer puts everything in your own user folders and does not need it.

Leave the window open for the next two steps.

Step 2. Check that the terminal can find Java 21

The applications run on Java 21, the same version your KSL projects use. You already have it, because your programs build in IntelliJ. The question is whether a terminal can find it. IntelliJ knows where its Java is; your terminal may not.

Type this command and press Return (or Enter):

java -version

Read the first line of what comes back.

  • It shows version 21 or higher, for example openjdk version "21.0.7". You are done with this step. Go to Step 3.
  • It shows a lower version, for example "17.0.12" or "1.8.0", or it says the command is not recognized or not found. Follow the fix for your computer below, then type java -version again until it shows 21 or higher.

The fix on Windows: set JAVA_HOME

This is the most common problem on Windows. IntelliJ keeps its Java in a hidden folder in your user folder, and nothing else on the computer knows it is there. You will tell Windows where it is by creating a setting called JAVA_HOME.

First, find the folder that holds IntelliJ’s Java 21.

  1. Open your KSL project in IntelliJ.
  2. Choose File > Project Structure….
  3. On the left, under Platform Settings, click SDKs.
  4. Click the SDK whose version is 21. The JDK home path box shows its folder, for example C:\Users\hsimpson\.jdks\corretto-21.0.7.
  5. Select the whole path in that box and copy it (Ctrl + C).

Next, give that folder to Windows.

  1. Click Start, type environment variables, and click Edit environment variables for your account. (Not the one that says system.)
  2. In the top box, User variables, click New….
    • Variable name: JAVA_HOME
    • Variable value: paste the path you copied.
    • Click OK.
  3. Still in the top box, click the variable named Path, then click Edit….
    • Click New and type %JAVA_HOME%\bin.
    • Click Move Up until it is at the top of the list.
    • Click OK.
  4. Click OK to close the Environment Variables window.

Finally, close PowerShell and open a new one. A terminal reads these settings only when it starts, so the old window does not see them. In the new window, type java -version again. It should now report version 21.

Set JAVA_HOME this way, in the Windows settings, and not by typing a command in PowerShell. A setting typed in PowerShell lasts only until you close that window, and the KSL applications, which start from the Start menu, would never see it.

The fix on macOS: install Java 21

On a Mac, the terminal and the applications use the newest Java installed in the standard places, and IntelliJ normally downloads its Java into one of them. If java -version still shows a version below 21, install a Java 21 that macOS knows about:

  1. Go to https://adoptium.net/temurin/releases/?version=21.
  2. Choose macOS, your Mac’s chip (aarch64 for Apple silicon M1 to M4, x64 for Intel), and the JDK, and download the .pkg file.
  3. Open the downloaded file and click through the installer.
  4. Close Terminal, open a new one, and type java -version again.

Not sure which chip you have? Click the Apple menu > About This Mac. “Chip: Apple” means aarch64; “Processor: Intel” means x64.

Step 3. Run the installer

The installer downloads the KSL suite (about 155 MB), checks it, and installs it. Copy the command for your computer, paste it into your terminal, and press Return.

macOS (one line):

curl -fsSL https://raw.githubusercontent.com/rossetti/KSL/main/install.sh | bash

Windows (one line):

irm https://raw.githubusercontent.com/rossetti/KSL/main/install.ps1 -OutFile "$env:TEMP\ksl-install.ps1"; powershell -ExecutionPolicy Bypass -File "$env:TEMP\ksl-install.ps1"

While it works, the installer prints lines that begin with *. The first ones should report your Java version and the download. It finishes in a minute or two, depending on your network.

It worked if it prints Done. followed by a short list of where things went, with no line that begins with error:. You can close the terminal now.

It did not work if you see error:. The two common ones are:

  • “Java not found” or “Java 21+ required”: go back to Step 2.
  • “Cannot install: these processes are still using …”: a KSL application or the KSL Server is running. See “Updating later” in the troubleshooting section.

The installer creates two folders:

Folder What is in it
~/Applications/KSL (Windows: %LOCALAPPDATA%\Programs\KSL) The software. You never need to open it.
~/Documents/KSLWork Your work: the reports and files the applications write, and a bundles folder for models.

The suite comes with the textbook’s example models already installed, so every application has models to run the first time it opens.

Step 4. Run one model in KSL Single

This step checks that the applications start and can run a model.

  1. Start KSL Single.
    • macOS: press Command + Space, type KSL Single, and press Return. (It is also in Launchpad.)
    • Windows: Start > KSL > KSL Single.
  2. A Pick a Model window appears. Choose the KSL Book Examples bundle, then the DriveThroughPharmacyWithQ model, and click Pick. This is the drive-through pharmacy from Chapter 4 of the textbook.
  3. The main window opens on the Run Control tab. Under Output Options, make sure HTML is ticked, so that a report opens when the run finishes.
  4. Click Simulate in the toolbar.

It worked if the status changes to Running…, the log counts up to 30 replications, and a report opens in your web browser with a table of results. Close the report and quit KSL Single.

If nothing happens when you start the application, see the troubleshooting section.

Step 5. Start the KSL Server and open its console

The KSL Server is a program that runs in the background. It has no window of its own. Instead, you watch it through a small status light and a web page called the console.

  1. Start KSL Server the same way you started KSL Single.
  2. Look for a small round status light:
    • macOS: in the menu bar at the top right of the screen.
    • Windows: in the system tray at the bottom right. If you do not see it, click the ^ arrow beside the clock to show the hidden icons.
  3. The light turns amber while the server starts, then green when it is ready. Gray means it is stopped.
  4. Click the light and choose Open Console. Your browser opens a page at http://127.0.0.1:3001/admin. Its header should show a green RUNNING light.

It worked if the console shows RUNNING. That page lives on your own computer; the address 127.0.0.1 always means “this computer”, so nothing is sent anywhere.

You can leave the server running, or click the light and choose Quit. Quitting stops it; you will start it again in class.

Step 6 (optional). Connect an AI coding assistant

Skip this step if you do not have a paid plan for an AI coding assistant. In class you can pair with a classmate who does, and you will still use your own console.

The server can connect to Claude Desktop, Codex, Cursor, or Windsurf. The assistant must be installed and signed in first. Free plans may not allow assistants to use servers like this one, or may allow so little use that the class activity cannot finish, so plan on a paid plan if you want to rely on it.

  1. With the KSL Server running, open its console (Step 5).

  2. In the Clients section at the top, click Connect beside your assistant. This writes the connection into the assistant’s settings for you.

  3. Quit the assistant completely and open it again. It reads its list of servers only when it starts. (Closing the window is not enough on a Mac; use Quit.)

  4. Ask the assistant:

    Use the ksl tools to search the textbook for event scheduling.

It worked if the assistant reports textbook sections with links to the book. The first request can take several seconds while the server loads its search index.

Before class checklist

Troubleshooting

java -version still shows the wrong version after the Windows fix. You are probably in the old PowerShell window. Close it and open a new one. If that is not it, open Edit environment variables for your account again and check two things: the JAVA_HOME value is the folder that contains bin (not the bin folder itself), and %JAVA_HOME%\bin is at the top of Path.

Windows says the script cannot be loaded or running scripts is disabled. You probably typed only the first half of the command. Copy the whole Windows command from Step 3; the -ExecutionPolicy Bypass part lets this one installer run without changing your computer’s settings.

macOS says an application “cannot be opened” or is “from an unidentified developer.” Open System Settings > Privacy & Security, scroll down, and click Open Anyway beside the KSL application’s name. You need to do this once.

A KSL application does nothing when you start it on Windows. The applications look for Java through JAVA_HOME. Go back to Step 2 and set it in the Windows settings, then sign out of Windows and sign back in, and try again.

The server light stays gray, or the console does not open. Quit KSL Server and start it again. If it still fails, another program may be using the server’s address. Open the console’s Diagnostics section if you can reach it, or bring the problem to class.

Updating later. To get a newer version, run the Step 3 command again; your work in KSLWork is kept. First quit every KSL application, quit the KSL Server (click its light, then Quit), and quit your AI assistant if you connected one. The installer refuses to update while any of them is still using the software, and it lists what is still running.

Something else. Copy the exact error message, or take a screenshot, and bring it to class.