Remote Connections and MPI

BlenderNEURON normally connects Blender and NEURON automatically on the same computer. Each application listens on 127.0.0.1, selects an available port, and writes its address to a file in the user’s private settings directory. The two applications discover each other’s addresses there and read the same local-secret file to authenticate requests. The secret is saved between sessions; it is not a temporary file that must be exchanged again at each start.

When NEURON runs in Docker or on another computer, it has a separate network and settings directory. Keep Blender on your local computer and configure the connection manually using the steps below. After connecting, use Getting Started to import and edit cells.

For MPI jobs or scripts that run to completion, use Offline Simulation Results instead. Configure recording in the script, run the simulation, and save a .bnresults file to import into Blender later. Blender does not need to be running during the job, and no pairing or network connection is needed. The Docker and SSH instructions below apply to live connections.

Connection addresses

Both applications receive requests, so both need a listening address and an address for the other application:

  • The listening address controls which interface an application receives requests on

  • The peer address tells that application how to reach the other application

  • Blender’s ‘NEURON address’ is interpreted from Blender’s computer

  • NEURON’s peer_address is interpreted from NEURON’s computer or container

127.0.0.1 always refers to the computer or container using the address. It does not refer to the other computer. With SSH forwarding, it can point to a tunnel entrance on the same computer, which carries requests to the other end. 0.0.0.0 is a listening address for all interfaces; do not use it as a peer address.

Throughout the manual connection examples, Blender uses port 8000 and NEURON uses port 8001. These are example fixed ports, not the automatically selected ports used for same-computer discovery. Choose available ports and update all matching settings and forwarding rules if you change them.

Where settings are saved

  • Windows: %LOCALAPPDATA%/BlenderNEURON

  • macOS: ~/Library/Application Support/BlenderNEURON

  • Linux: $XDG_CONFIG_HOME/blenderneuron (or ~/.config/blenderneuron)

This directory holds the local secret, discovery address files, and saved connection settings. Set BLENDERNEURON_CONFIG_DIR to use another private directory, such as a persistent container volume. Credentials are stored outside the .blend file. Do not put them in a shared repository. Unix files use private permissions; Windows uses the user profile directory’s permissions. Processes running as the same user can read them.

Pairing information

Manual pairing gives both applications the same authentication secret. In the Python session running your NEURON model, run:

from blenderneuron.neuronstart import BlenderNEURON
print(BlenderNEURON.pairing_information())

The output is a JSON string with three fields. For example (the secret below is a placeholder):

{"version": 1, "secret": "<64 hexadecimal characters>", "address": "http://127.0.0.1:8001"}

  • version identifies the pairing information format, currently 1

  • secret is the 64-character authentication secret that both applications must share

  • address is the exporting application’s listening URL, including its port

The exported address is not necessarily reachable from the other application. For example, NEURON’s 127.0.0.1 inside Docker refers to the container, while Blender’s 127.0.0.1 refers to the host. After importing pairing information, replace the address and port with the ones reachable from the receiving application, as shown in each example below. Keep the secret unchanged.

  1. In Blender’s ‘Node Status’, press ‘Connect to NEURON…’ (or ‘Change connection…’ for a saved connection)

  2. Choose ‘In Docker or on another computer’

  3. Use ‘Copy Python command’ to get the command above and run it in NEURON

  4. Copy the full JSON output, including the braces, and press ‘Paste from clipboard’ in Blender

    • You can also enter ‘NEURON address’, ‘NEURON port’, and ‘Pairing secret’ manually

  5. Set the addresses and listening ports for your setup using the Docker or SSH steps below

  6. Press ‘Connect’ (‘OK’ in Blender 4.0)

The settings are remembered. Use ‘Reconnect’ after restarting either application. Reconnecting restores communication; it does not reload the model or recreate cell groups and Blender objects.

Warning

Pair only with processes you trust: a paired process can execute Python in the other application. Keep the JSON and secret private, including clipboard contents. Authentication does not encrypt HTTP traffic. Use SSH tunnels between computers.

Connection settings in Python

configure_connection sets NEURON’s listening interface and port, the address it uses to reach Blender, and optionally pairing information copied from Blender:

BlenderNEURON.configure_connection(
    mode="manual",
    listen_host="127.0.0.1", listen_port="8001",
    peer_address="http://127.0.0.1:8000",
    pairing=blender_pairing_string)

In this example, NEURON receives requests on port 8001 and reaches Blender on port 8000. The loopback addresses work when both applications are on the same computer, or when using the SSH tunnels below. For Docker, use the host address reachable from the container as shown in the next section.

blender_pairing_string is the JSON copied with ‘Copy Blender connection information’ in the dialog’s ‘Advanced’ section. Omit pairing when using NEURON’s secret and importing its JSON into Blender instead. The explicit peer_address overrides the address in the imported JSON.

Restart the NEURON node/process after changing its listening interface or port. Then retrieve its pairing information. Use BlenderNEURON.test_connection() to check whether Blender is authenticated and reachable from NEURON.

Connect to Docker

In this example, Blender runs on the host and NEURON runs inside a container. NEURON listens on container port 8001; Blender listens on host port 8000. Docker publishes NEURON’s port on the host, so Blender sends requests to host port 8001. NEURON sends requests back directly to Blender’s host port 8000.

Port

On the host (Blender’s computer)

Inside the container

8000

Blender listens here

No listener; NEURON sends requests to the host’s port 8000

8001

Docker publishes this port and forwards to container port 8001

NEURON listens here

  1. Publish NEURON’s port when starting the container by adding this option to docker run:

    -p 127.0.0.1:8001:8001

    The format is host-address:host-port:container-port. Here, host port 8001 forwards to container port 8001. Blender reaches the published port at 127.0.0.1:8001 on the host; this is Blender’s ‘NEURON address’ and port, not Blender’s own listening address and port.

  2. Choose a host IP address reachable from the container

    For this example, assume the host has address 192.168.1.10 and the container can reach it. Replace this example IP with your host’s reachable address in both Blender’s listening settings and NEURON’s peer_address. Do not use the container’s IP here.

  3. In Blender’s connection dialog, select ‘In Docker or on another computer’ and expand ‘Advanced’

    • Set ‘Listen address’ to the host’s reachable IP (192.168.1.10 in this example)

    • Enable ‘Use a fixed listening port’ and set it to 8000

    • Allow connections from the container to this interface and port through the host firewall

  4. In the container’s NEURON Python session, configure:

    from blenderneuron.neuronstart import BlenderNEURON
BlenderNEURON.configure_connection(
    mode="manual", listen_host="0.0.0.0", listen_port="8001",
    peer_address="http://192.168.1.10:8000")

    listen_host="0.0.0.0" lets NEURON receive Docker’s forwarded requests on container port 8001. peer_address="http://192.168.1.10:8000" tells NEURON to send requests to Blender’s port 8000 on the host. Using 127.0.0.1 here would send requests to the container itself.

  5. Restart the NEURON node/process and copy its pairing JSON into Blender as described above

  6. In Blender, set ‘NEURON address’ to 127.0.0.1 and ‘NEURON port’ to 8001, then press ‘Connect’

The two request paths are:

Blender on host -> host 127.0.0.1:8001 -> Docker forwarding -> NEURON container :8001
NEURON container -> host 192.168.1.10:8000 -> Blender

The host address used for the return path depends on your Docker network setup. Publishing NEURON’s port sets up only the first path; it does not make Blender’s host loopback listener reachable from inside the container. Docker on Windows and macOS also uses a separate container network.

Connect to a Remote Machine through SSH

Blender and NEURON both send requests to each other. SSH therefore needs two tunnels: one to reach NEURON from Blender, and one to reach Blender from NEURON. This example uses port 8000 for Blender and port 8001 for NEURON:

Port

On your local computer

On the remote computer

8000

Blender listens here

SSH listens here and forwards to local Blender port 8000

8001

SSH listens here and forwards to remote port 8001

NEURON listens here

Each port number is used on both computers. Port 8000 belongs to Blender locally and to its SSH tunnel entrance remotely. Port 8001 belongs to NEURON remotely and to its SSH tunnel entrance locally. Reusing the numbers works because the listeners are on different computers. All listeners use 127.0.0.1 on their own computer.

These port numbers are examples. Choose available ports and keep the application settings and SSH forwarding command consistent if you change them.

  1. In Blender’s connection dialog, choose ‘In Docker or on another computer’ and expand ‘Advanced’

    • Set ‘Listen address’ to 127.0.0.1 (Blender’s local computer)

    • Enable ‘Use a fixed listening port’ and set it to 8000

  2. In the remote NEURON Python session, configure:

    from blenderneuron.neuronstart import BlenderNEURON
BlenderNEURON.configure_connection(
    mode="manual", listen_host="127.0.0.1", listen_port="8001",
    peer_address="http://127.0.0.1:8000")

    listen_port="8001" is NEURON’s own receiving port on the remote computer. peer_address="http://127.0.0.1:8000" tells NEURON where to send requests for Blender: to SSH’s port 8000 on that same remote computer. SSH forwards those requests to Blender’s port 8000 on your local computer. The SSH command below creates this tunnel.

  3. Restart the NEURON node/process to apply its listening settings

  4. On your local computer, run:

    ssh -N -L 8001:127.0.0.1:8001 -R 8000:127.0.0.1:8000 user@remote

    • Replace user@remote with your SSH account and the remote hostname or IP

    • Leave this terminal running while using BlenderNEURON

    • -L 8001:127.0.0.1:8001 creates a local SSH listener on port 8001 and forwards requests to NEURON’s remote port 8001

    • -R 8000:127.0.0.1:8000 creates a remote SSH listener on port 8000 and forwards requests to Blender’s local port 8000

    The request paths are:

    Local computer                         Remote computer
----------------                       ----------------
Blender
  | requests to local :8001
  v
SSH listener :8001 ---- SSH ---------> NEURON :8001

Blender :8000 <-------- SSH ---------- SSH listener :8000
                                         ^
                                         | requests to remote :8000
                                       NEURON

    All listeners in this diagram use 127.0.0.1 on their own computer.

  5. Copy NEURON’s pairing JSON into Blender using the pairing steps above

  6. In Blender, set ‘NEURON address’ to 127.0.0.1 and ‘NEURON port’ to 8001, then press ‘Connect’

    Blender’s address points to the SSH listener on your local computer, rather than directly to the remote computer. NEURON’s peer address points to the SSH listener on the remote computer.

Keep the computers’ clocks synchronized; authenticated requests allow 60 seconds of clock difference. If a jump host is required, add -J user@login and use the computer running NEURON as the destination. Follow your site’s access and port forwarding rules.

Use NEURON with MPI

Use the saved-results workflow for MPI simulations:

  1. Configure groups and activity recording in your simulation script after building the local cells on each rank

  2. Run the simulation using your model’s initialization and solver code

  3. Call SimulationExport.save() on every rank; rank 0 writes one combined .bnresults file

  4. After the job finishes, copy the file to your Blender computer

  5. In Blender’s ‘Import / Export’ panel, press ‘Import Saved Simulation Results…’ and select the file

For a complete example, run this command from the repository root on the machine running NEURON:

mpiexec -n 2 nrniv -mpi -python tutorials/offline_simulation.py

This script configures recording, runs a short simulation, and saves simulation.bnresults in the working directory. Use your cluster’s launcher or job submission command as appropriate. Blender can remain closed until you are ready to import the file.

See Offline Simulation Results for the script API, group settings, and importing recorded activity. To collect different activity or change the model, update and rerun the script, then import the new results file.