Running API Simulator


A Standalone API Simulator instance is a Java process running in its own JVM (Java Virtual Machine).

Starting and Stopping

Assuming <api-simulation-directory> is the path to a directory with simulation configuration, quick way to start an API Simulator instance for the simulation is to execute:

apisimulator start <api-simulation-directory>

For example:

apisimulator start /tests/apisims/payments-simulation

This command requires the current directory to be the bin directory under the simulator’s installation, or to have that directory already added to the PATH environment variable. Otherwise, use fully qualified path to the apisimulator script.

API Simulator will be listening on the default port 6090 and its admin server will be running on port 6190. Both API Simulator and its admin server are part of the same process and run in the same JVM (Java Virtual Machine).

The admin server listens for commands like the stop command to shut down the API Simulator remotely.

To stop the API Simulator started with the command above, execute:

apisimulator stop <api-simulation-directory>

The simulation directory is only needed for the stop command to assure that the log for the shutdown ends up in the simulation’s directory.

Multiple API Simulators

Can multiple API Simulators run on the same host? Yes, absolutely:


There is no limitation on the number of API Simulator instances on a host - just use different port numbers for the API Simulators and their admin servers.

Command-line Arguments

API Simulator supports a number of arguments. Each command-line argument also has a respective JVM -D argument.

Command-line arguments are to be specified after the path to the simulation:

apisimulator start <api-simulation-directory> <command-line-arguments>

apisimulator stop <api-simulation-directory> <command-line-arguments>

Here is a table with the supported arguments:

Command-line Argument JVM -D Argument Description

-h <arg>

Simulator host. Useful when there are multiple network interfaces. Optional.

-p <arg>


Simulator server port number. Optional.

-s <arg>


Path to simulation configuration (directory). Automatically provided when using the apisimulator script.

-c <arg>


Comma-delimited list of hierarchical configuration directories. Automatically provided when using the apisimulator script.

-scripts <arg>


Comma-delimited list of paths to directories with scripts. Surround with double quotes paths that contain spaces. Automatically provided when using the apisimulator script.

-d <arg>


Name of the default simlet. Must match the directory name of the default simlet. Optional.

-charset <arg>


Default charset. Optional.

-key_store <arg>


File specification of Java key store (JKS) for configuring TLS. Use together with -key_store_password and -key_password as needed.

-key_store_password <arg>


Java key store (JKS) password for configuring TLS. Use together with -key_store and -key_password as needed.

-key_password <arg>


Key password. Use together with -key_store and -key_store_password as needed.

-self_signed_cert_fqdn <arg>


Fully qualified domain name (FQDN) for self-signed certificate issued at run-time. Use on its own to configure TLS.

-certificate <arg>


Certificate file in PEM format for TLS configuration. Use together with -private_key.

-private_key <arg>


Private key file in PEM format for TLS configuration. Use together with -certificate.

-admin_host <arg>

Admin server host. Useful when there are multiple network interfaces.

-admin_key <arg>


Value of the key/passphrase, if the admin server is secured. Required to stop an API Simulator instance remotely if a key/passphrase was supplied at startup time.

-admin_port <arg>


Admin server port number.


Starts an API Simulator instance for a simulation.



Shuts down an API Simulator. Which API Simulator is stopped is determined by the port number of its admin server


Run API Simulator on port 8080 and its admin server on port 8090:

apisimulator start <api-simulation-directory> -p 8080 -admin_port 8090

apisimulator stop <api-simulation-directory> -admin_port 8090

Run API Simulator on port 8000, its admin server on port 9999, and secure the admin server with a key:

apisimulator start <api-simulation-directory> -p 8000 -admin_port 9999 -admin_key 1^pnD0wn

apisimulator stop <api-simulation-directory> -admin_port 9999 -admin_key 1^pnD0wn

Run API Simulator on its default port 6090 and configure TLS using self-signed certificate issued at run-time:

apisimulator start <api-simulation-directory> -self_signed_cert_fqdn

apisimulator stop <api-simulation-directory>

Environment Variables

The following optional environment variables control various aspects of configuring API Simulator:

Environment Variable Description


Makes it possible to start API Simulator using a Java installation different from the one JAVA_HOME points to.


Maximum and/or minimum JVM heap size and other memory-related settings.

Linux, macOS:

export APISIMULATOR_HEAP_SIZE="-Xms256m -Xmx256m"


set "APISIMULATOR_HEAP_SIZE=-Xms256m -Xmx256m"


Logging configuration file - fully qualified path and name, or just file name. File name only can be specified if the file is located in one of the default locations per simulation. By default, start and stop use different logging configuration files.


Allows specifying one or more comma-separated directories with scripting files.


Other JVM options and arguments except heap size. For example, Garbage Collector settings.

We would love to hear your feedback! Shoot us a quick email to [feedback at] to let us know what you think.

Happy API Simulating!