Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
How to: set up Desktop App environments and updates
The Desktop App is one packaged build that any number of people point at any
number of evenfire instances — your production tenant, a staging tenant, or a
local make-forwarded cluster. This guide covers adding and switching
environments, the three setup paths, and how the app handles updates.
For packaging and shipping the build itself, see
Ship it to your users.
When you need this
- You run more than one instance (say, staging and production) and want to switch between them in one app.
- You are onboarding through an invitation rather than a shared login.
- You distribute a packaged build and want users to know when a new release requires them to update.
Self-hosted first administrator
The first Control Admin created by the self-hosted /admin/auth/setup bootstrap
is a separate setup path from invitation onboarding. The Desktop identity
provisioned for that admin is linked directly for GFS operator access when the
self-hosted deployment enables the operator-link setting. Control UI displays
the exact pair and provides Revoke/disable Desktop GFS operator access;
revoking it removes only GFS authority and preserves the admin account,
passwords, identities, and unrelated permissions. The same surface provides an
explicit Reactivate Desktop GFS operator access action that creates a new
generation from retained history; it never restores a revoked row in place.
Retiring the linked Control Admin revokes the active generation before the
admin is disabled. Invitations and ordinary member provisioning do not create,
repair, or reassign this link.
The environment model
You save only the External REST API URL for an instance. The app then asks that API for the display name and RPC proxy URL when the environment is saved or selected. Startup also retries discovery for a saved profile without an RPC URL. Discovery can happen before sign-in; there is no second URL to type or include in a Profile UI link.
If discovery fails before sign-in, authentication can still succeed. A later health check can discover and use RPC for the live session without changing its saved environment, credential slot, chat binding, or GFS scope. Settings shows the saved RPC URL and display name, so it may still show an empty RPC URL while RPC health is healthy. The discovered URL and name are saved at the next safe signed-out boundary. If that optional save fails, authentication still ends and a later health check retries discovery and persistence. A failed team switch that clears the session also clears its live RPC override.
Setup paths
Three ways to add an environment; all of them end with the same saved environment.
1. Manual, from the sign-in screen
Click the + beside Environment, give it a name and the External REST API URL, and save. Both fields are required. The app discovers the RPC proxy before sign-in, then you can sign in with the configured REST and RPC endpoints.
For a local minikube cluster, follow the Quickstart port-forwards and point the environment at the forwarded External REST API.
2. From Profile UI, by deep link
When Profile-to-Desktop handoff is enabled, a member can open the environment from Profile UI → Settings → Setup desktop app. Desktop selects a single saved environment with the matching REST endpoint, including its API path and query. URL matching ignores fragments and trailing path slashes and normalizes a terminal DNS root dot. A different path on an already-saved origin is rejected for manual resolution. If the current session uses another REST URL, Desktop asks before switching. Cancel keeps the current session signed in; confirming signs out and then selects the matching saved environment. If no exact match is saved, Desktop asks before adding the environment; after confirmation, the External REST API supplies the RPC proxy URL before sign-in. Duplicate saved matches are rejected unless the already-active environment itself matches the requested REST endpoint; that exact active environment is retained.
The handoff is disabled by default. A release operator can enable it by setting
the PROFILE_DESKTOP_HANDOFF_ENABLED repository variable to true when
building Profile UI, after releasing the updated Desktop client and retiring
older supported clients. Changing the repository variable alone does not build
a new image: the normal build runs only when Profile UI source paths change, or
the Build & Publish workflow can be dispatched with build_all=true to
rebuild every image. Production promotion reuses the digest built from dev, so
rebuild Profile UI before promotion when the variable was the only change.
Before enabling the handoff, verify that EXTERNAL_REST_API_PUBLIC_BASE_URL
and CONTROL_API_DESKTOP_EXTERNAL_REST_API_BASE_URL point to the same REST
endpoint, including the API path. Matching only the hostname is not sufficient.
While the handoff is disabled, copy the REST API URL from Profile UI Settings
and add it from Desktop's sign-in screen. Fleets can also be pre-seeded with a
CLERUM_DESKTOP_CONFIG_PATH config file (see
Ship it to your users).
3. Through an invitation
When the app starts with no selected environment, it runs invitation
detection. Completing the Profile UI invitation
flow hands the app a setup token (an evenfire://desktop-setup deep link); the
app then saves the tenant environment by name and discovers its RPC proxy.
Gap: the invitation email and the Profile UI signup flow above can now run with nothing extra to deploy, via control-api's hosted mode — see Member invitations on self-hosted. Completing the handoff into the Desktop App itself still depends on
member-registration-service, which is not in this repo. See the member-registration gap for what still works without it.
Localhost
Localhost always sits at the bottom of the environment list. In a packaged build it stays unselected until you pick it, so invitation detection can run on first launch; running through local dev commands selects it by default.
Updates
After you authenticate, the app checks the currently selected tenant for its
update policy, so different tenants can be on different versions at the same
time. It asks that tenant's External REST API for its release info, including a
minimumDesktopVersion. If the installed version is below that minimum, the
app shows a Desktop update required dialog; Download update opens the
releaseUrl the server returns (the release tagged v<desktopVersion>) in
your browser. (A packaged distribution is where this matters most — a source
checkout can just pull the latest.)
This is update detection, not silent auto-install: the app tells the user an update is required and links the release; it never downloads or installs on its own. macOS signing and notarization are available as an opt-in build step, and Windows and Linux builds are unsigned — see Ship it to your users.
Troubleshooting
- Wrong instance after switching — each environment caches its own RPC proxy; re-open the Environment screen and confirm which instance is selected.
- Stale RPC proxy — re-running the Profile UI Setup desktop app for an already-saved External REST API updates the name and clears the cached RPC proxy so it is re-discovered.
- Signed in to the wrong tenant — authentication is per environment; sign out, reselect the environment, and sign in again.
Related
- Desktop App surface — screens, packaging, env vars
- Profile UI — the invited-member entry point
- Quickstart — local minikube bring-up