Open a JITX editor on another machine#

Run the design and native runtime on a runtime host, and open the native board or schematic editor on a client machine. SSH port forwarding carries the editor connection to the runtime’s WebSocket listener. Open the native editor with the JITX CLI command below.

Use the same native runtime version on both machines and the project’s pinned Python dependencies.

1. Start the design on the runtime host#

Work from the project root with its pinned Python environment activated. Install the compatible production runtime, record its version with introspect, and start it:

jitx runtime install --prod
jitx runtime introspect
jitx runtime start --background
jitx runtime status

Run jitx design find and replace mypkg.main.MyDesign throughout this note with the reported design name. Start the persistent session described in JITX AI Agent Integration and Interactive Design Sessions:

jitx design session mypkg.main.MyDesign

Leave that session terminal open. Note the port in the WebSocket address reported by runtime status, for example 56106. The editor’s --port takes only that number. Keep the runtime host awake.

Enable SSH access from the client through your organization’s LAN or VPN:

Host	Setup reference
Windows	Install and start OpenSSH Server and allow the SSH service through the firewall.
macOS	Enable Remote Login for the intended account.
Linux	Install and enable the distribution’s OpenSSH server; Ubuntu instructions.

The tunnel connects to loopback on the runtime host. Permit SSH between the machines; a separate inbound rule for the runtime port is unnecessary for this procedure.

2. Forward the port from the client#

Run this in the client’s terminal or PowerShell, substituting the runtime port, SSH account, and host:

ssh -o ExitOnForwardFailure=yes -N -L 127.0.0.1:55173:127.0.0.1:56106 engineer@runtime-host

Leave the tunnel running. Here 55173 is the local client port and 56106 is the runtime host’s port. Choose an unused local port. Add -p SSH_PORT if SSH uses a nondefault port. See the OpenSSH forwarding reference.

3. Open the native editor on the client#

Use a local project copy and activate its pinned environment. Install the host’s native version to obtain the editor; replace HOST_VERSION with the version recorded on the host. Arrange client download access and authorization with JITX.

jitx runtime install --prod --version HOST_VERSION
jitx runtime introspect
jitx ui open --board --port 55173 --design mypkg.main.MyDesign

Confirm the version with introspect. Replace --board with --schematic to open the schematic editor. --port connects to the tunnel without looking for a local runtime.

4. Use a fixed host port when useful#

The automatically assigned port can change after a restart. To select a fixed port, choose an unused value, stop the host runtime, set the variable in its launch environment, then start it again.

Windows PowerShell:

jitx runtime stop
$env:JITX_INTERACTIVE_SERVER_PORT = "56106"
jitx runtime start --background

macOS or Linux:

jitx runtime stop
export JITX_INTERACTIVE_SERVER_PORT=56106
jitx runtime start --background

Confirm the selected port with jitx runtime status. Restart the host’s design session using step 1, then reconnect the tunnel and editor. Restarting the runtime closes its connected sessions.

Troubleshooting and agent access#

Symptom	Check
SSH forwarding fails	Verify SSH login, host firewall policy, and whether the client port is already occupied.
Editor cannot connect	Check host runtime status, the tunnel process, and the client-side port passed to `--port`.
Editor opens without the expected design	Verify the fully qualified name and that the host has loaded the design.
Connection fails after a restart	Restart the design session, check the new runtime port, and reconnect the tunnel and editor.
UI or protocol mismatch	Inspect the native runtime version on both machines and the project CLI version.

Run an agent’s design session and design exec commands in the project on the runtime host; neither accepts --port. A file-based exec also needs its script on that host. The editor tunnel does not provide filesystem access.