Installation Guide

CupCarbon Klaines 8.0 — step by step, for every platform

1. Requirements 2. Packages 3. Windows 4. macOS M 5. macOS Intel 6. Linux 7. First launch 8. Settings & projects 9. Uninstall 10. Troubleshooting

1. Requirements

Two free tools are needed, whatever the platform:

2. Choosing your package

CupCarbon Klaines is distributed as one zip per platform. Each zip contains the application (cupcarbon.jar, JavaFX included — no --module-path options needed), a double-clickable launcher and the utils/ runtime resources (offline map backgrounds, Python examples, executor configuration).

PlatformPackageLauncher
Windows (x64)cupcarbon_windows.zipcupcarbon_win.bat Download
macOS — Apple Silicon (M1–M4)cupcarbon_macos_m.zipcupcarbon_macm.command Download
macOS — Intelcupcarbon_macos_x.zipcupcarbon_macx.command Download
Linux x64cupcarbon_linux_x.zipcupcarbon_linux.sh Download
Linux ARM (Raspberry Pi 4/5, ARM servers)cupcarbon_linux_m.zipcupcarbon_linux.sh Download
The five distribution packages of CupCarbon Klaines 8.0.
Which macOS package? Apple menu → About This Mac. “Chip Apple M…” → Apple Silicon package (4). “Processor Intel…” → Intel package (5). Choosing the wrong one produces an “incompatible architecture” error at start (see Troubleshooting).

3. Windows (x64)

  1. Install Java 17+ and Python 3 (tick “Add python.exe to PATH” in the Python installer).
  2. Download and unzip cupcarbon_windows.zip anywhere (e.g. Documents).
  3. Open the cupcarbon_windows folder and double-click cupcarbon_win.bat.
  4. If Microsoft Defender SmartScreen shows a warning the first time, click More info → Run anyway.

4. macOS — Apple Silicon (M1, M2, M3, M4)

  1. Install Java 17+ (choose the aarch64 / Apple Silicon build) and Python 3.
  2. Download and unzip cupcarbon_macos_m.zip.
  3. Double-click cupcarbon_macm.command.
  4. First launch only — macOS Gatekeeper may refuse: right-click (Ctrl-click) the file → Open → Open. If needed, allow it in System Settings → Privacy & Security.

5. macOS — Intel

  1. Install Java 17+ (choose the x64 build) and Python 3.
  2. Download and unzip cupcarbon_macos_x.zip.
  3. Double-click cupcarbon_macx.command (first time: right-click → Open → Open).

6. Linux (x64 and ARM)

  1. Install Java 17+ and Python 3. On Ubuntu / Debian / Raspberry Pi OS: 
    sudo apt install openjdk-21-jre python3
  2. Download and unzip the package matching your processor (uname -m → x86_64 = Linux x64, aarch64 = Linux ARM).
  3. In a terminal, inside the unzipped folder: 
    chmod +x cupcarbon_linux.sh    # first time only
./cupcarbon_linux.sh

7. First launch

  1. Create a project: File → New project. A CupCarbon project is a plain folder (nodes, scripts, GPS routes, agentic workflows, results) that you can move, zip and share.
  2. Add IoT nodes: press key 2 then click the map, or use console commands such as add iot 25.3020 55.4855.
  3. Program the nodes in Python: open the Program editor (toolbar), start your script with from cup_functions import * and use the cup_* functions (full list with examples behind the editor's Help button). If scripts do not start, set the Python command in the Executor Path Configuration window (python3, python, or a full path).
  4. Run: click Run IoT Simulation. For the agentic AI workflows, click the 🤖 toolbar button — see the Agentic AI documentation.

8. Where settings and projects are stored

WhatLocation
Settings: recent projects, executor paths, AI API keys the utils/ folder next to the jar when it is writable; otherwise a per-user folder — macOS ~/Library/Application Support/CupCarbon, Windows %APPDATA%\CupCarbon, Linux ~/.config/cupcarbon
Projectswherever you create them (File → New project)
AI API keysaiagent.cfg in the settings folder — entered via the workflow editor's API Keys button, never shipped with CupCarbon

9. Updating and uninstalling

Update: download the new zip and replace the old folder — projects are elsewhere and are not affected. Uninstall: delete the CupCarbon folder, and optionally the settings folder listed above. CupCarbon writes nothing anywhere else.

10. Troubleshooting

ProblemSolution
“java: command not found” or nothing happens Java is missing or too old: install 17+ from adoptium.net and check java -version.
“UnsatisfiedLinkError … incompatible architecture (have 'x86_64', need 'arm64')” (or the reverse) Wrong package for your processor: download the other macOS (or Linux) package. Also delete the JavaFX cache: rm -rf ~/.openjfx/cache.
macOS: “cannot be opened because it is from an unidentified developer” Right-click the .command file → Open → Open (first launch only).
Windows: SmartScreen warning More info → Run anyway.
IoT scripts don't run Check the Executor Path Configuration (Python reachable) and that a script is assigned to each node.
Python TabError Open the script in the Program editor: tabs are highlighted — click Tabs → Spaces.
Map empty or slow without internet Switch to an offline background (Map menu). Tile downloads time out after a few seconds and never block the application.
AI Agent answers “no rule matched” The LLM was not reached: check the provider selected on the node and your API key (API Keys dialog).

Next steps: the Tutorials and the Simulator Help.