Skip to content

RunningHeadless

Jump to bottom
RoiArthurB edited this page Jul 29, 2026 · 8 revisions

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.

Home

  1. What's new (Changelog)
  2. Migration Guide (2025-06 → 2026-06)

Platform

  1. Installation and Launching
    1. Installation
    2. Launching GAMA
    3. Updating GAMA
    4. Installing Plugins
  2. Workspace, Projects and Models
    1. Navigating in the Workspace
    2. Changing Workspace
    3. Importing Models
  3. Editing Models
    1. GAML Editor (Generalities)
    2. GAML Editor Tools
    3. Validation of Models
  4. Running Experiments
    1. Launching Experiments
    2. Experiments User interface
    3. Controls of experiments
    4. Parameters view
    5. Inspectors and monitors
    6. Displays
    7. Batch Specific UI
    8. Errors View
  5. Running Headless
    1. Getting Started
    2. Headless Legacy
    3. Headless Batch
  6. Preferences
  7. Troubleshooting

Learn GAML step by step

  1. Introduction
    1. Start with GAML
    2. Organization of a Model
    3. Basic programming concepts in GAML
  2. Manipulate basic Species
  3. Global Species
    1. Regular Species
    2. Defining Actions and Behaviors
    3. Interaction between Agents
    4. Attaching Skills
    5. Inheritance
  4. Defining Advanced Species
    1. Grid Species
    2. Graph Species
    3. Mirror Species
    4. Multi-Level Architecture
  5. Defining GUI Experiment
    1. Defining Parameters
    2. Defining Displays Generalities
    3. Defining 3D Displays
    4. Defining Charts
    5. Defining Monitors and Inspectors
    6. Defining Export files
    7. Defining User Interaction
  6. Classes and Objects
    1. Class Definition and Instantiation
    2. Attributes and Actions
    3. Inheritance
    4. Virtual Classes
    5. Advanced Features
  7. Exploring Models
    1. Run Several Simulations
    2. Batch Experiments
    3. Exploration Methods
  8. Optimizing Models
    1. Runtime Concepts
    2. Analyzing code performance
    3. Optimizing Models
  9. Multi-Paradigm Modeling
    1. Control Architecture
    2. Defining Differential Equations

Recipes

  1. Manipulate OSM Data
  2. Cleaning OSM Data
  3. Diffusion
  4. Using Database
  5. Using Dataframes
  6. Using FIPA ACL
  7. Using BDI with BEN
  8. Using Driving Skill
  9. Manipulate dates
  10. Manipulate lights
  11. Using comodel
  12. Save and restore Simulations
  13. Using network
  14. Writing Unit Tests
  15. Ensure model's reproducibility
  16. Going further with extensions
    1. Calling R
    2. Using Graphical Editor
    3. Using Git from GAMA

GAML References

  1. Built-in Species
  2. Built-in Skills
  3. Built-in Architecture
  4. Statements
  5. Data Type
  6. File Type
  7. Stats Extension
  8. Sound Extension
  9. BDI Extension
  10. FIPA Skill
  11. Expressions
    1. Literals
    2. Units and Constants
    3. Pseudo Variables
    4. Variables And Attributes
    5. Operators (Definition)
    6. Operators [A-A]
    7. Operators [B-C]
    8. Operators [D-H]
    9. Operators [I-M]
    10. Operators [N-R]
    11. Operators [S-Z]
  12. Exhaustive list of GAMA Keywords

Developing GAMA

  1. Installing the development version
    1. Install GAMA source code with Eclipse plugin
  2. Developing Extensions
    1. Developing Plugins
    2. Developing Skills
    3. Developing Statements
    4. Developing Operators
    5. Developing Types
    6. Developing Species
    7. Developing Control Architectures
    8. Index of annotations
  3. Introduction to GAMA Java API
    1. Architecture of GAMA
    2. IScope
  4. Using GAMA flags
  5. Creating a release of GAMA
  6. Documentation generation

Tutorials

  1. Predator Prey
  2. Road Traffic
  3. Incremental Model
  4. Luneray's flu
  5. BDI Agents
  6. Forager RL
  7. SIR Analysis
  8. 3D Model

Community

  1. Team
  2. Projects using GAMA
  3. Scientific References
  4. Training Sessions

Versions of GAMA

Resources

  1. Videos
  2. Conferences
  3. Pedagogical materials

Clone this wiki locally