Skip to main content

Connect a remote Runtime target

This page completes one task: connect the current App to a Runtime target on another industrial PC, edge device, or site server. If you are not sure whether you need a remote target, start with Runtime and site delivery.

Connecting and binding do not upload the project, replace an App, or change runtime state. After this task, follow the delivery plan to Build, Start, or Debug.

Before you start​

  • Obtain the exact target name and complete access address, such as https://runtime.example.com.
  • Confirm that the development computer can reach the target network. HTTP remains available on a protected local network; use trusted HTTPS for cross-network or production remote management.
  • Have an Admin account owned by that target. For first-time setup, decide who owns the first Admin and its recovery process.
  • Confirm whether this is a test or production target and obtain approval to connect to the site network.

Target accounts, Qixin online-service accounts, and App users have different responsibilities. See Runtime target accounts and permissions when you need to choose the correct account.

warning

Before connecting to a production target, verify the machine, physical location, network, and certificate. A familiar name or a reachable address does not prove that it is the approved target for this task.

Find nearby runtimes​

In Manage Runtime Targets, click Find nearby runtimes and wait about five seconds. Results show each device name, instance ID and address. Add target fills the existing form; save, then check and sign in as described below. Searching never switches your execution target automatically.

The device must advertise discovery on the same local network. Allow local-network access when prompted. You can still enter an address manually if nothing is found. Devices across routers or VLANs usually do not appear. Local development runtimes do not advertise on the LAN.

Discovered names and addresses are candidates. Connections still validate HTTPS certificates, which must match the selected IP; you can enter a trusted hostname manually instead.

Add and check the target​

  1. Open the target App in the editor.
  2. Open the Runtime target selector in the toolbar, then enter Manage Runtime Targets.
  3. Select Add target.
  4. Enter a site-recognizable name and the complete access address.
    • Include only the scheme, host, and port.
    • Do not append /api, a Page path, query parameters, or account information.
  5. Select Save.
  6. Select Check on the target row.
  7. Confirm that the target is Reachable, then compare the reported machine information with the site record.

If the check fails, resolve the address, DNS / IP, port, firewall, network, or certificate problem before attempting authorization.

Connect and bind the current App​

  1. Select Connect on the checked target row.
  2. Continue according to the target state:
    • Uninitialized target: create the first target Admin and preserve recovery information through the site process.
    • Initialized target: sign in with an Admin owned by that target.
  3. After authorization succeeds, bind the target to the current App.
  4. Reopen the Runtime target selector and verify all of the following:
    • The name and access address are correct.
    • The target is Bound and Reachable.
    • The current target session is Admin.

The selection is the global execution target on this development computer. After switching, later Build, Start, and Debug operations in open Apps display and use the new target. Local files, Git repositories, AI conversations, and editor settings do not move to the remote target.

Use the command line​

Desktop and terminal commands share the same SDK-owned target catalog and current selection:

theseus runtime discover
theseus runtime list
theseus runtime add factory-a https://runtime.example.com
theseus runtime use factory-a
theseus runtime status

runtime add accepts an HTTP or HTTPS origin without an /api path, Page path, query, or fragment. runtime use accepts either a name or an id returned by list. When a remote target is no longer needed, run theseus runtime remove <name-or-id>; the built-in Local target cannot be removed. A CLI selection becomes Desktop's current target after its next refresh.

Success criteria​

  • The current App toolbar names the approved remote target.
  • Target details show Bound, Reachable, and Admin together.
  • The name, address, and machine information match the test or production record.
  • The existing App and runtime state on the target did not change merely because of connection.

Return to Runtime and site delivery for the Save, Build, Start, and acceptance loop. To configure a site terminal, see Use Theseus Player on a site terminal.

Common issues​

The target is Unreachable​

Check the address, DNS / IP, port, site network, firewall, and whether the target is online. Make sure the address has no API or Page path appended.

When should I switch from HTTP to HTTPS?​

HTTP targets remain connectable but should stay on a protected local network. For cross-network or production remote management, use the target's trusted HTTPS address or establish a secure network path according to site policy. Do not disable certificate checks.

The target says Setup required​

The machine has no target accounts yet. The designated owner creates the first Admin and records credential custody and recovery. Do not initialize a machine whose ownership is unclear.

The target says Admin required or cannot be bound​

The current target session is not Admin or has expired. Reconnect with an Admin owned by that target. Qixin sign-in and an Admin role inside the App cannot replace it.

The target is bound, but the current App is missing​

This is expected: connection does not deliver the project. Review the existing App and state on the target, then follow Build and runtime acceptance. Obtain downtime approval before replacing another App.

What a person must confirm​

  • The target name, address, machine, and physical location identify the same approved device.
  • The HTTPS certificate and network path meet site-security requirements.
  • The current person is authorized to use target Admin access.
  • Connecting to a production target is not mistaken for deployment or production approval.