Connect to a remote gateway
Use the desktop app with a server while keeping your local installation.
The desktop app can display its built-in gateway and gateways you run on servers. Each gateway owns its own agents, conversations, providers, and settings. Connecting one does not merge databases or migrate a local agent.
Before connecting
Have the server's panel address, such as https://jian.example.com, and its owner token, JIAN_API_TOKEN. Use the base address that serves the panel and forwards /v1; do not append /v1 or use the internal Docker hostname.
The desktop accepts HTTP or HTTPS addresses without embedded credentials, query parameters, or fragments. Prefer HTTPS outside a trusted local connection. The standalone Jian Remote installer has a stricter HTTPS requirement.
Connect from the desktop app
- Open the gateway picker and choose Connect a gateway.
- Enter the Address and Host token.
- Choose Connect. Jian verifies the gateway before keeping the connection.
- Select it in the picker. Its agents and settings now populate the panel.
The host token is kept by the app's main process using its credential storage; it is not exposed to the renderer window. It grants owner access to that gateway, so do not substitute a channel token or a machine worker token.
Version compatibility
The desktop panel and a published gateway must share their major.minor release line. For example, 1.1.3 and 1.1.4 are compatible; 1.1.x and 1.2.x are not treated as the same line. Keep the desktop and server current together when crossing release lines.
Development builds without a normal release version are not compared in the same way. That exception is not a deployment compatibility guarantee.
Let the server use this computer
Displaying a remote gateway is separate from allowing it to operate this machine. The desktop's computer-sharing control governs the app-managed worker.
When sharing is enabled, Jian registers this computer on reachable server gateways saved in the app and runs a worker for each. The switch is computer-wide, not a separate permission for the currently visible gateway. Turning it off stops those workers; their machine records remain on the gateways.
The local gateway is excluded from this server-sharing registration. You do not need to add it as a second remote gateway.
See Jian Remote for the execution model and Computer Use for OS permissions. A server being online does not mean a machine it depends on is online.
What survives disconnecting
Switching gateways does not stop the server. Removing a gateway from the app removes the client's saved connection and stops its app-managed worker; it does not delete that server's agents or database. The web panel remains another way to access the same server state.
If you need to move an agent between installations, do not treat adding a gateway as an import operation. This connection flow performs no data migration.
Troubleshooting
| Symptom | Check |
|---|---|
| Address cannot be reached | DNS, HTTPS certificate, reverse proxy, and /health at the panel address |
| Token is refused | The server's current JIAN_API_TOKEN; token type and accidental whitespace |
| Release mismatch | Desktop and gateway major.minor versions |
| Chats work but computer actions fail | Sharing switch, machine online status, worker version, OS permissions |
| Server agents disappear after switching | You selected another gateway; their state remains on the original server |
Implementation reference
Connection dialog, compatibility rules, and computer-sharing lifecycle.