Connect to a SoAI server

SoAI Connect remembers one server at a time. Scan the QR code from the WebUI or enter the address of the server, check the result, and sign in with the same account you use in the WebUI.

Prepare the server in the SoAI WebUI

  1. Open the WebUI on a computer. If the Setup wizard appears, finish it and select Create account on the Create administrator account step.
  2. To make a separate account for the phone, an administrator with User administration (USER_ADMIN) permission can select the Settings button at the right of the header, choose Settings, select Users, then select Create user. See Administration overview for the full account and ACL workflow.
  3. If you run SoAI OS and have SoAI OS administration (HOST_MANAGEMENT_ADMIN) permission, open Network from the sidebar. Use the IP ADDRESS shown on the connected network card. With SoAI Core, use the hostname or LAN IP that already opens the WebUI from another machine.
  4. Put the phone on the same LAN or VPN as the server unless you have configured secure remote access.
  5. To pair by QR code, select the Settings button at the right of the header, choose Settings, then select Connect. Every signed-in user can open this tab. It shows a QR code with the address it points to underneath, and when the server has more than one usable address, Address for your phone lets you pick the one the phone can reach.

Do not enter localhost or 127.0.0.1; on the phone, those names point back to the phone. An address such as 192.168.1.100 or soai.local is usually enough. The app also accepts IPv6 and full http:// or https:// URLs. Add :port when more than one instance runs on the host.

Connect for the first time

Scan the QR code

  1. Open the Connect tab in the WebUI.
  2. In SoAI Connect, select the QR code button at the right of the server address field and allow camera access when asked.
  3. Point the camera at the code. The scanner closes as soon as it reads a SoAI Connect code, fills in the address, and checks the server.

When the server that answers has the same instance, scheme, and port as the code, the app connects without another tap. A private or self-signed certificate still opens the certificate prompt, so compare the fingerprint before you trust it. If discovery fell back to another scheme or port, or the connection would use HTTP to a public address, the app stops on the result so you can read the warning and select Connect yourself.

Enter the address

  1. Open SoAI Connect and enter the server address.
  2. Select Check.
  3. Check the instance name, SoAI version, URL, active port, and connection security shown on screen.
  4. Select Connect.
  5. If the server uses a private or self-signed certificate, the certificate prompt appears before the WebUI loads. Compare its SHA-256 fingerprint with the one supplied by your administrator, then select Trust once or Trust always.
  6. Sign in on the SoAI page.

After the first connection, the app opens this server directly. To start over, open the app's Settings, then Data, and select Change server.

Server discovery

If you omit the port, SoAI Connect checks discovery ports 7950 through 7960. It validates the answer and then checks the server's health endpoint. If the server moved to a fallback runtime port, the result shows both the configured port and the port in use.

If two instances answer on the same host, SoAI Connect does not choose between them. Enter an explicit port for the instance you want. An explicit http:// URL without a port uses port 80, and an explicit https:// URL uses port 443.

Choose a safe transport

Connection What SoAI Connect does Recommended use
HTTPS with a public certificate Uses Android's normal certificate validation. Use this when the private LAN or VPN hostname has a certificate that Android trusts.
HTTPS with a private or self-signed certificate Shows the subject, issuer, and SHA-256 fingerprint before it loads the WebUI. Compare the fingerprint through a separate trusted channel before you approve it.
HTTP on a private network Allows the unencrypted connection. Keep it on a trusted LAN or inside an encrypted VPN.
HTTP to a public address Warns that anyone between the phone and server can read the session. Configure HTTPS before signing in.

For a private certificate, Trust once keeps approval for the current app session. Trust always pins the certificate fingerprint to that server origin and instance (not merely its hostname). If the private or otherwise untrusted certificate changes, SoAI Connect stops the request and asks you to review the new fingerprint. Remove a saved pin under Settings, Security, Reset Trusted Certificate.

SoAI Connect does not support client-certificate authentication. Keep the server on the private boundary described in Security hardening. An administrator with Configuration changes (CONFIG_PATCH) and ACL administration (ACL_ADMIN) permissions should select the Settings button at the right of the WebUI header, select Settings from its menu, open Security, and resolve every item in the Security hardening audit. Use HTTPS for the connection.

Connection problems

Message or symptom What to check
Certificate changed Compare the new fingerprint with the server before you replace the saved pin.
Invalid server address Enter a hostname, IPv4 address, bracketed IPv6 address, or HTTP/HTTPS URL without spaces.
IPv6 zone identifiers are not supported Replace a scoped address such as fe80::1%wlan0 with a hostname or supported address.
Multiple SoAI servers were found Enter hostname:port for the instance you want.
Server not found Check that discovery ports 7950 through 7960 reach the server, or enter its runtime port.
Server not reachable Confirm that SoAI is running. In SoAI OS, an account with SoAI OS administration (HOST_MANAGEMENT_ADMIN) permission can open Network in the SoAI WebUI and check that the selected network card is Connected and still has the address you entered.
Only reachable from this computer The Connect tab shows this when SoAI listens on a loopback address, which the phone cannot reach directly. Set SERVER.HTTP.NETWORK.HOST to 0.0.0.0 and restart SoAI, or publish it through a reverse proxy that uses the same scheme and port as SoAI, because SoAI Connect rejects a server that answers on a different scheme or port than the one it contacted.
No reachable address found The server has no usable network address. Connect it to a network and select Refresh addresses on the Connect tab, or open the WebUI from the address the phone should use.
This QR code belongs to a different SoAI server The address in the code reached another SoAI instance. Select Refresh addresses, choose the address the phone can reach, and scan again.
This QR code needs a newer version of SoAI Connect Update SoAI Connect, then scan the code again.
Camera access is needed to scan a QR code Allow camera access for SoAI Connect in the phone's app settings, or type the server address instead.
The endpoint responded but is not a SoAI server Check the address and port. Another service may be listening there.
The WebUI opens but sign-in fails Use an account from this server. An administrator with User administration (USER_ADMIN) permission can select the Settings button at the right of the header, choose Settings, then select Users.

Related documentation