Running Headless
What is GAMA Headless​
Headless mode allows GAMA to run simulations without a graphical user interface. This is useful for:
- Running experiments on a cluster, grid, or CI/CD pipeline
- Reducing memory footprint and improving performance
- Integrating GAMA as a backend service for other applications (Python, JavaScript, etc.)
- Running batch experiments or headless server interactions programmatically
In headless mode, GAMA is used only to run experiments. Editing or managing models is not possible. For preparing experiments with a UI, launch GAMA normally and follow the Running Experiments guide for GUI experimentation.
Three Headless Modes​
GAMA provides three distinct headless modes:
| Mode | Use Case | How Experiments Are Defined |
|---|---|---|
| Legacy | Simple one-shot runs, older models | Manually written XML experiment plan files |
| Batch | Automated batch exploration | Defined directly in your .gaml model as a batch experiment |
| Server | Interactive remote control via WebSocket | Dynamic commands sent at runtime (load, step, pause, expression, etc.) |
Getting Started​
Option 1: Using the Bash Wrapper (Recommended)​
The wrapper script provides the simplest way to launch headless simulations.
Linux/macOS: headless/gama-headless.sh
Windows: headless/gama-headless.bat
Basic syntax:
gama-headless.sh [options] <launchMode> [arguments]
General headless options:
| Option | Description | Example |
|---|---|---|
-m <memory> | Memory allocation | -m 8g |
-c | Console mode (read experiment plan from stdin) | -c |
-hpc <cores> | Limit parallel simulation count | -hpc 4 |
-v | Verbose mode (show console output) | -v |
-socket <port> | Start headless server on port | -socket 6868 |
-batch <expName> <model.gaml> | Run batch experiment | -batch Optimization model.gaml |
-xml <expName> <model.gaml> <out.xml> | Generate XML experiment plan | -xml Exp model.gaml plan.xml |
<plan.xml> <outputDir> | Run legacy experiment from XML | plan.xml results/ |
Get full help:
./gama-headless.sh -help
Quick example — run a batch experiment:
./gama-headless.sh -batch MyBatchExperiment /path/to/model.gaml
Quick example — run legacy mode with explicit XML plan:
./gama-headless.sh /path/to/plan.xml /path/to/results/
Quick example — launch headless server:
./gama-headless.sh -socket 6868
Option 2: Direct JVM (Advanced)​
For fine-grained control or custom build integrations:
java -cp $GAMA_CLASSPATH -Xms512m -Xmx2048m -Djava.awt.headless=true \
org.eclipse.core.launcher.Main -application gama.headless.product [options]
Note: The bash wrapper is strongly recommended. It handles classpath setup, JVM flags, and workspace management for you.
Option 3: Docker​
A Docker image is available at gamaplatform/gama:
docker run -v /your/workspace:/working_dir -p 6868:6868 gamaplatform/gama -socket 6868
See gama.docker for full documentation.
Next Steps​
Choose your headless mode based on your use case:
- Headless Legacy — XML-based experiment plans, good for simple scripted runs
- Headless Batch — batch experiments defined in your GAML model (most natural for GAMA users)
- Headless Server — interactive WebSocket API for full programmatic control
Calling GAMA from Other Languages​
Python (Headless Server)​
The gama-client Python package provides a wrapper for the HEADLESS server API:
pip install gama-client
See the GitHub repository for the latest examples and documentation.
JavaScript/TypeScript​
A WebSocket client is available in the same gama.clients repository, with examples like MapBox visualizations and interactive syntax examples.