RunningHeadless - gama-platform/gama GitHub Wiki

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.

⚠️ **GitHub.com Fallback** ⚠️