Arguments and Settings

Command-line arguments can be used to tweak some parameters of BeamNG.tech before the simulation starts. This page contains a list of all such parameters useful for BeamNG.tech.

How to Use

To run BeamNG.tech with command-line arguments, you can use the following instructions depending on your operating system.

Windows

Start an instance of “Command Prompt” and use the following commands to run BeamNG.tech with command-line arguments.

cd /d C:/path/to/BeamNG.tech
Bin64\BeamNG.tech.x64.exe -arg1 -arg2 -arg3

You can also create a shortcut to the BeamNG.tech.x64.exe executable with the New → Shortcut option in Windows context menu. You can set the arguments in the Properties of this shortcut.

Create a new shortcut in the desired location Create a new shortcut in the desired location Set the arguments in the shortcut properties Set the arguments in the shortcut properties

Linux

Start an instance of a terminal and use the following commands to run BeamNG.tech with command-line arguments.

cd /path/to/BeamNG.tech
BinLinux/BeamNG.tech.x64 -arg1 -arg2 -arg3

Connect to BeamNGpy

These arguments are used to control the connection to BeamNGpy. BeamNGpy always tries to connect to an existing BeamNG instance, but it will be successful only if the BeamNG instance started the server. If BeamNGpy doesn’t manage to connect, it will try to launch a new BeamNG session.

To start BeamNG.tech instance which is ready to be connected to BeamNGpy and listens to connections on 127.0.0.1:25252 (the default), use the following arguments.

Windows: Bin64\BeamNG.tech.x64.exe -tcom -console
Linux: BinLinux/BeamNG.tech.x64 -tcom

After launching BeamNG, you can use BeamNGpy to connect to the existing instance:

from beamngpy import BeamNGpy
beamng = BeamNGpy('localhost', 25252) # Replace with the IP/port you specified if not default
beamng.open() # Connect to BeamNG.tech

print(beamng.system.get_info()) # Gets information about host system
{'type': 'GetSystemInfo', 'tech': True, 'os': {'buildNumber': 2.0, 'versionMinor': 4.0, 'shortname': 'Ubuntu', 'type': 'linux', 'fullname': 'Ubuntu VERSION="24.04.2 LTS (Noble Numbat)"', 'gamearch': 'x64', 'bits': 64.0, 'versionMajor': 24.0}}

Listening on Other Network Interfaces

The BeamNGpy protocol is unencrypted, unauthenticated and allows arbitrary Lua code execution! Do not bind on IP addresses that are available to the public, use only protected networks or the local interface.

You can set the -tport and -tcom-listen-ip to listen on another port/address. In this example, BeamNG starts a server listening on 192.168.0.3:12345.

Bin64\BeamNG.tech.x64.exe -tcom -console -tport 12345 -tcom-listen-ip 192.168.0.3

Troubleshooting

You can use a custom BeamNGpy Wireshark plugin to debug the communication protocol on the network layer.

Debugging BeamNGpy using Wireshark Debugging BeamNGpy using Wireshark


Arguments List

The list of BeamNG.tech related arguments follows.

BeamNGpy

  • -tcom: Starts the BeamNGpy server, by default on 127.0.0.1:25252.
  • -tport N: Sets the TCP port on which the BeamNGpy server listens to N.
  • -tcom-listen-ip X.X.X.X: Sets the IP address on which the BeamNG.tech server binds and listens to BeamNGpy clients.
  • -tcom-debug: Enables the BeamNG.tech communication debug mode. That has multiple effects: the Capture Player is automatically recording captures in this mode, and also errors in BeamNGpy protocol crash the communication and full stacktrace is shown.

Physics

  • -physicsfps N: Sets the number of physics steps per second to N. By default, N=2000. Too high values of N can result in slower-than-realtime simulation and unexpected behavior.

Graphics

  • -gfx dx11 (Windows only): Sets the rendering API to DirectX 11 (default for Windows).
  • -gfx vk: Sets the rendering API to Vulkan (default for Linux).

Headless Mode

  • -headless: Enables headless mode (no window shown). For more information, see the Headless Mode documentation page.

Security

There are multiple sandboxes which can be controlled by the usage of the BeamNG.tech arguments:

  1. Lua sandbox: Limits the usage of LuaJIT API to reduce the possibility of running malicious code (shared library loading, unsafe memory operations, etc.).
  2. Network sandbox: Limits the IP addresses and domains that BeamNG can connect to.
  3. CEF renderer sandbox: A feature of the Chromium Embedded Framework which protects the browser renderer process.

In the default configuration of BeamNG.tech, the Lua sandbox is disabled, the network sandbox is enabled, and the CEF renderer sandbox is enabled. This may change in the future to the security-by-default approach.

  • -enable-sandbox: Enables the Lua sandbox and enables the network sandbox.
  • -disable-sandbox: Disables the Lua sandbox and disables the network sandbox.
  • -nosandbox: Disables the network sandbox only. The name of this argument is in place for historical reasons.
  • -nocefsandbox (Linux only): Disable the CEF renderer sandbox. This can be used to bypass the error “The SUID sandbox helper binary was found, but is not configured correctly” which occurs on some Linux configurations (Docker, Ubuntu 24.04).

Annotations

  • -partannotationconfig: Configuration file for colors of vehicle part annotations. Used by the Impactgen project.
  • -annotationconfig: Configuration file for colors of object annotations. Used by the Impactgen project.

Miscellaneous

  • -console (Windows only): The extra console window is open on start.
  • -colorStdOutLog (Linux only): Standard output of the program is colored depending on the logging level of the shown messages.
  • -lua CHUNK: Runs a chunk of Lua code during BeamNG startup.
  • -luastdin: BeamNG accepts Lua commands from the standard input.
  • -luadebug: Starts a Lua debugging server on port 21110, which can be used to debug BeamNG.tech using the Lua Remote Debugger for Visual Studio Code extension.
  • -attachOnStart: Usable only with -luadebug. The simulator waits until debugger is attached before starting.
  • -batch: Runs in non-interactive mode (no system dialogs are shown).
Last modified: April 15, 2025

Any further questions?

Join our discord
Our documentation is currently incomplete and undergoing active development. If you have any questions or feedback, please visit this forum thread.