Running Multiple MoveIt Pro Instances on One Computer
A single computer can run several MoveIt Pro deployments at the same time — for example two simulated cells, or one deployment per robot in a test lab. Each deployment is a named instance with its own containers, network namespace, published ports, persistent data directory, and logs, so instances never interfere with each other.
Instances support mock hardware, simulation, and direct-device hardware (for example USB cameras). Network-attached robot hardware that opens connections back into the MoveIt Pro stack requires the default host-network deployment — run at most one of those, without --instance.
Starting an instance
Pass --instance <name> to moveit_pro run:
moveit_pro run --instance robot-a
Instance names use lowercase letters, digits, - and _, and must start with a letter or digit.
Ports are assigned automatically. The first time an instance runs, MoveIt Pro picks a free block of six consecutive host ports, starting from 10000. The first port remains unused for compatibility with existing port registries; the remaining ports serve the REST API, WebSocket bridge, video signaling, WebRTC media, and terminal. The assignment is recorded in ~/.config/moveit_pro/instance_ports.yaml, so an instance keeps the same ports on every later run.
Running without --instance is the default deployment and keeps Runtime services on 3200–3203—3203 being the WebRTC media port—discovery on 3204, and the terminal service on 3205. Auto-assigned instance ports never overlap with these ports, so the default deployment and named instances can run side by side.
To pin an individual service port, set the matching environment variable before moveit_pro run; the rest of the block stays auto-assigned. Pinned ports must be 1024 or higher and outside the reserved ports 3200–3205. MOVEIT_WEBRTC_MEDIA_PORT has one extra restriction: it is published on the same number inside the container as outside (MediaMTX writes its own bind port into the WebRTC connection details it hands the client), so it must also avoid 13201, 13202, and 13204, which services inside the container already use:
MOVEIT_REST_PORT=12000 moveit_pro run --instance robot-a
Run each instance from its own terminal. Different instances can use different robot configuration packages:
moveit_pro run --instance robot-a --config-package my_cell_a_config
moveit_pro run --instance robot-b --config-package my_cell_b_config
What each instance gets
| Resource | Location |
|---|---|
| Containers, networks | Docker Compose project moveit_pro_<name> |
| Host ports | Auto-assigned block recorded in ~/.config/moveit_pro/instance_ports.yaml |
| Reserved compatibility port | First port in the assigned block; no service listens on it |
| Persistent data | ~/.local/share/moveit_pro/instances/<name> (override with MOVEIT_HOST_DATA_DIR) |
| ROS logs | ~/.ros/log_moveit_pro/<name> |
| CLI log | ~/.config/moveit_pro/last_moveit_pro_run.<name>.log |
Instances are isolated at the network level: each one runs in its own network namespace, so their ROS 2 traffic never mixes, even without configuring distinct ROS_DOMAIN_ID values. All instances on a host share the same Docker images, so disk usage does not multiply with the number of instances.
The network isolation relies on the DDS configuration that MoveIt Pro manages (loopback interface, no multicast, local peers). Instances refuse to start when a custom DDS configuration is active — USE_HOST_DDS=true, a custom CYCLONEDDS_URI value or FASTRTPS_DEFAULT_PROFILES_FILE, a non-default RMW_IMPLEMENTATION, or overridden CYCLONEDDS_* discovery settings — because custom discovery settings can route traffic between instances. Deployments that need a custom DDS configuration must use the default deployment (run without --instance).
Managing instances
List all recorded instances and their running state:
moveit_pro run --list-instances
Target a specific instance with the --instance option on the other CLI verbs:
# Open a shell in an instance's container
moveit_pro shell --instance robot-a
# Shut an instance down completely
moveit_pro down --instance robot-a
moveit_pro down without --instance only shuts down the default (non-instance) deployment; named instances keep running until brought down individually.
Licensing
All instances on one host share a single license activation. The hardware fingerprint identifies the machine, not the instance, so running several instances on one computer does not consume several activations. You need one activation per machine, however many instances it runs.
The fingerprint is derived from the machine's hardware — its TPM where one is available, otherwise its permanent network hardware address — and is stable across restarts, container recreation, and network changes. Nothing needs to be configured per instance, and this works the same whether or not the instance uses host networking.
Two machines each running instances need one activation each, as before.
Discovering instances
When discovery is enabled on a supported host, MoveIt Pro lists recorded deployments, their service ports, and whether their REST TLS service is running on one DNS-SD-advertised discovery endpoint. Running unsaved instances appear as separate Runtimes in the desktop app. For saved connections with a frontend key, the app can authenticate the Runtime and distinguish Not Ready from Running. Each app window connects to one Runtime; select File > New Window to use another instance at the same time. For discovery and secure access from another computer, see Network Discovery.
Limitations
- Remote access requires direct reachability to the discovery and Runtime service ports. During each connection, the desktop app authenticates the instance's current TLS certificate with its frontend key; see Network Discovery and Endpoint Security.