Installation and Updates
You can install adaptor:ex on your computer or laptop, or run it on a server (Local vs. Server).
The fastest way to try adaptor:ex locally is the Desktop Installation. If you need more control or want to set up adaptor:ex for your team, we recommend the installation via NPM or Docker.
Desktop Installation
Download adaptor:ex for your operating system and save the file in your Apps folder.
Version 2.11.1 (June 11, 2026)
When you run adaptor.ex, a command line will automatically start and your default browser will open the adaptor:ex Web Editor.
Follow the Getting Started guide to take your first steps with adaptor:ex.
NPM und Docker
You can also install adaptor:ex via NPM or Docker, or use the source code.
-
Install via NPM Package Manager
With the NPM Package Manager you can easily install adaptor:ex from the command line on any common operating system and run it as an NPM application.
We recommend the Installation via NPM Package Manager if you want to use adaptor:ex locally on your computer or in an internal network.
A local installation allows you to use the ports on your computer. E.g. the serial port via USB or a sound card.
-
Especially for a server installation we recommend the Install in a Docker Container.
You can use our Docker Compose file to create a comprehensive and stable setup with independent server and client application and MongoDB integration.
The Server Setup tutorial will help you install adaptor:ex with Docker and Docker Compose on an external server, secure it, and make it accessible to everyone working on your project.
-
Download the adaptor:ex source code and use NPM to install and run the server application and client independently.
An install from source allows you to make changes to the software. We recommend installing from source if you want to customize some code or contribute to the development of adaptor:ex.
Install with NPM
Before you can proceed with the installation of adaptor:ex, you need the latest version of NodeJS. You can find the necessary installation files for your operating system here.
Once you have installed NodeJS, open your console or terminal and run the installation from the command line with npm
Note
Note the hint Nodejs and Windows PowerShell if you use Windows PowerShell.
If the installation was successful, start adaptor:ex with the command
You can find ways to configure adaptor:ex in the adaptor:ex server readme
To stop adaptor:ex server use the key combination
Ctrl+C
Cmd+C
or type quit and hit Enter in the command line.
Updates with NPM
Update to the latest version of adaptor:ex with
You can always check wether a new version is available using
Installing with Docker
Download Docker for your operating system and follow the installation instructions at https://docs.docker.com/get-docker/
Create a new folder where you want to install adaptor:ex.
Open your command line, change to the adaptor:ex directory with the cd command and download the adaptor:ex docker-compose file:
curl -o docker-compose.yml https://gitlab.com/machina_ex/adaptor_ex/adaptor_ex_server/-/raw/main/docker-compose.yml
Download the config file for the adaptor:ex client:
Execute the Docker Compose file:
adaptor:ex server, client, database and plugin extensions are downloaded and installed.
If you want to access adaptor:ex from a remote location, you must specify the external URL or IP of the adaptor server application in
adaptor_client_config.json. Inhttp://localhost:8081/api, replace "localhost" with the IP of the machine on which you have set up the docker container, or with the URL of your server or machine.
For a save setup on a remote server we recommend following the Server Setup tutorial.
In the adaptor:ex server readme you can learn more about the configuration of adaptor:ex.
Updates with Docker
To update the adaptor:ex Docker installation change to the adaptor:ex directory. There execute the following commands:
and
Installing from Source with NPM
Before you can proceed with the installation of adaptor:ex, you need the latest version of NodeJS. You can find the necessary installations files for your operating system here.
Get adaptor:ex server and client:
server
Clone the current GitLab repository of the adaptor:ex server via:
Or download here: https://gitlab.com/machina_ex/adaptor_ex/adaptor_ex_server
Client
Clone the current GitLab repository of the adaptor:ex client via:
or download here: https://gitlab.com/machina_ex/adaptor_ex/adaptor_ex_client
Now you can install the server and the client locally with NPM.
In the terminal (console) change to the directory where you have loaded or cloned the server or client.
or
and run the following command in both directories:
Note
Note the hint Nodejs and Windows PowerShell if you use Windows PowerShell.
If the installation was successful, start the adaptor:ex server in the corresponding directory with the command
Before you start the client in a separate command line, you must specify the address the server can be reached on. In the adaptor_ex_client/public directory open config.json and change the value for API_URL. If server and client are running on the same computer with default settings, that would be http://localhost:8081/api.
{
"API_URL": "http://localhost:8081/api",
"_COMMENT_LOG_STORE": "Set 'true' to print every store action and mutation",
"LOG_STORE": false,
"_COMMENT_LOG_SOCKET": "Set 'true' to print every socket message",
"LOG_SOCKET": true,
"LOG_SOCKET": false,
"_COMMENT_LOG_LEVEL_APP": "Set select wicht toast notifications to show. Can be 'debug', 'info', 'warn', 'error'.",
"LOG_LEVEL_APP": "debug"
}
Then start the adaptor:ex client in the appropriate directory with
Updates with git
Download the latest version of adaptor:ex server and client by updating the git repository in the respective directory with the following command
Restart the adaptor server and client.
Notes
Local vs. Server
Depending on how you want to use adaptor:ex, it might be more convenient to install the application on your computer or laptop or on a server.
A local installation allows you to use the connections on your computer. For example:
- the serial port via USB
- a sound card to play audio on your computer
- a DMX box to control lights from your computer
If you use a server, you cannot use the hardware on your PC, but you gain other advantages:
- All team members always have access to the current game project
- IoT devices can communicate with adaptor:ex over the internet
- Mobile devices, phones, and tablets can connect to the adaptor:ex server
- You don't need to keep your computer switched on to have your game project online 24/7
If you can't do without both, you can also turn your local computer into a server with some additional configuration or set up a Raspberry Pi so that it can be reached from the internet.
Command Line Terminal
To install adaptor:ex via NPM, Docker, or source code, you need to use the command line of your operating system.
On MacOS, search for the program "Terminal".
On Linux, you can open the terminal with the key combination Ctrl+Alt+T.
On Windows, search for the application "Command Prompt" or "cmd".
Configuration
The adaptor:ex server application offers various ways to customize your installation. All configuration options are described in the Readme of the adaptor:ex server code repository.
Some functions of the adaptor:ex server can also be controlled via the command line: Commands
NPM
If you have installed adaptor:ex via NPM, add configuration options to the adaptorex command, for example:
Docker
If you are running adaptor:ex in a Docker Compose setup, append the options to the entrypoint of the adaptorex server container. For example:
services:
adaptorex-server:
image: registry.gitlab.com/machina_ex/adaptor_ex/adaptorex-server:latest
entrypoint:
[
"node",
"index.js",
"--headless",
"-d",
"mongodb",
"-m",
"mongodb://mongodb:27017/?replicaSet=adaptor-repl",
"--log",
"debug"
]
Desktop
Even if you are using the desktop version of adaptor:ex, you can run the app with options via the command line.
On MacOS, run the app with open --args in the Applications folder.
On Linux, go to the folder where you downloaded adaptor:ex and run the .AppImage file
On Windows, use the Powershell to run the adaptorex.exe with options. ```console .\adaptorex.exe --log debug
Multi User Server Setup
Take a look at the Server Setup tutorial to install adaptor:ex with Docker and Docker Compose on an external server. Here you can also find out how to secure internet access to adaptor:ex and make it accessible to everyone working on your project.
Updates
We will frequently fix bugs, improve things (hopefully), and add new features in the future. Update by downloading the current Desktop Installation or by running an update via NPM or Docker.
News about updates will be published in the News Blog and on our Discord Channel.
Nodejs and Windows PowerShell
In the basic configuration, npm cannot be executed on Windows PowerShell. To allow execution, the Execution Policy must be changed.
To be able to install adaptor:ex, run the PowerShell as administrator and enter this command:
Get help
Contact us if you are having trouble installing adaptor:ex. Write us at tech@machinaex.de or check out our Discord channel.