Desktop app on your deployment

Install the official Sim desktop app and connect it to your deployment. You do not need a custom build to change servers. The app is currently macOS-only; use the web app on other platforms. See Sim Desktop for general installation and use.

Server prerequisites

Use the origin your server serves, including scheme, hostname, and port. Paths are ignored.
HTTPS is required except for localhost, 127.0.0.1, and ::1, which allow HTTP for local testing.
Do not include credentials in the URL.
Use a certificate trusted by macOS.
Allow your Sim server to reach api.github.com and github.com for official installer and update lookup.

Install and connect

1
Resolve the installer
From your installation directory:
Code
```
bunx sim-setup desktop
```
The command reads Compose/Helm configuration, resolves the installer, and prints the download link and server URL. It offers to open the installer in your browser. Use --no-open to skip that prompt, or supply the public origin directly:
Code
```
bunx sim-setup desktop --url https://sim.example.com --no-open
```
--url skips discovery. Without the CLI, open https://<your-sim-origin>/api/desktop/update/download in a browser.
Install the app
Open the .dmg and drag Sim to Applications. Official installers are signed and notarized by Sim.
Connect to your server
Launch Sim, choose Sim → Server…, enter your deployment origin, and select Connect. The app relaunches against that server and saves the setting across updates.

What changes when you switch servers

Each server has its own cookie and storage partition. Switching clears deployment-scoped state before the new server loads:

State	Result
Sign-in session	Sign in to the new deployment.
Saved route	Open the workspace picker rather than the old deployment's workspace.
Folder access	Grant directories again when needed.
Built-in browser sessions	Sign in to sites again.

Window size, zoom, theme, notification preferences, tray, and launch-at-login settings remain. If deployment-scoped state cannot be cleared, the switch is refused; retry to complete it.

Recover a wrong server URL

The Can't connect page reports a DNS, timeout, or TLS failure. Select Change server to open the picker with the current value prefilled. No filesystem change is needed to correct a typo.

A private or self-signed certificate must be trusted by macOS; otherwise the app shows Connection isn't secure. A correct URL does not bypass certificate validation.

Installer and update endpoints

Your deployment exposes two public endpoints:

Endpoint	Response
`/api/desktop/update/download`	`302` to the newest official installer for the deployment channel.
`/api/desktop/update/latest-mac.yml`	`200` with a `text/yaml` update manifest.

Both resolve official GitHub release assets and cache lookups for five minutes. They return 404 when the channel has no release and 502 when GitHub lookup fails or candidates lack valid desktop artifacts.

The server serves release selection and the manifest; clients download installers from GitHub. These endpoints cannot distribute your custom artifacts. Set GITHUB_TOKEN on the Sim server if its shared egress IP reaches GitHub's unauthenticated 60-requests/hour limit; authenticated user-token requests typically allow 5,000/hour. See GitHub rate limits.

Deployment channel

APPCONFIG_ENVIRONMENT selects the channel:

Value	Channel	Repository
`dev`	`dev`	`simstudioai/sim-desktop-releases`
`staging`	`staging`	`simstudioai/sim-desktop-releases`
Anything else, including unset	`latest`	`simstudioai/sim`

Unavailable update feed

A feed 404 with the no-release header means no update is available. For 502, timeout, or connection failure:

A stable build eligible for self-update falls back to Sim's packaged GitHub feed.
A dev or staging build skips the check because the stable fallback cannot update its bundle identity.
Other builds receive no update offer until the deployment feed answers again.

Self-update requires a Developer ID build installed in Applications. Other packaged builds can offer manual downloads when the feed works. Release selection therefore follows your deployment only while its feed answers; an eligible stable app can use the fallback during an outage.

CLI discovery and probe failures

The installer probe is required: failure exits 1. Update-feed failure is a warning and still exits 0 if the installer resolved, so read both results before relying on updates.

If detected configurations name different NEXT_PUBLIC_APP_URL origins, the command lists them and requires --url; there is no interactive selection. If none names an origin, it defaults to http://localhost:3000. --url also avoids the Docker/Helm discovery calls.

Build a custom shell

Use a custom build for a different bundle identity or signing identity, such as distribution through MDM with your organization's Developer ID. Start from a source checkout with dependencies installed. Packaging requires macOS with Xcode 26 or later for the Icon Composer asset.

Code

cd apps/desktop
SIM_DESKTOP_DEFAULT_ORIGIN=https://sim.example.com bun run package:mac

The default origin applies to fresh installs; the server picker remains available. The macOS target builds a universal binary. Output files are apps/desktop/release/Sim-<version>-universal.dmg and .zip. Pass -c.appId=com.example.sim to choose a bundle identifier.

The baked default determines the app's channel identity, userData directory, and single-instance lock. Loopback, dev.sim.ai, and staging.sim.ai defaults produce separate Local, Dev, and Staging app identities; other origins use the production Sim identity. A Local build can still be pointed at another HTTPS server, but changing servers does not turn it into a production build or change its update eligibility.

package:share instead writes apps/desktop/release/<channel-slug>/<channel-slug>-<version>-<arch>.<ext> and disables trusted timestamps. Use package:mac for notarized distribution.

Runtime override

SIM_DESKTOP_ORIGIN overrides the saved server for one launch. It uses the same validation as the picker; an invalid value is logged and ignored. The override does not replace the saved server setting.