# Desktop app

> A graphical provider client for macOS and Linux that sets up and runs endpoints on this machine and on remote Linux machines over SSH.

Source: https://0.0.0.0:3000/docs/providers/desktop
Documentation index: https://0.0.0.0:3000/docs/llms.txt

The desktop app is a graphical client for the same provider agent the terminal UI and CLI use. It sets up endpoints, publishes models and prices, diagnoses problems and shows earnings, on this computer and on remote Linux machines over SSH. It can also install endpoints as background services and keep the agent updated.

Profiles, publication rules and statuses are the same in the desktop app, the terminal UI and the CLI, so you can set up an endpoint in one and run it from another. Endpoints run as separate processes: closing the app or losing an SSH connection never stops them.

## Install

The app is distributed separately from the agent, as signed packages that include a copy of the agent.

| Platform | Package |
| --- | --- |
| macOS 14 or later on Apple silicon | DMG |
| Linux x64 and ARM64 (glibc) | AppImage, DEB, RPM |

The app and the `numes` command share one installation per user account, with the same profiles and the same optional `config.toml`. When this computer has no installation, the app installs its bundled agent; when you already installed the agent with the [installer](/docs/providers/install-and-update), the app uses that installation. The app doesn't install inference engines or download models.

## What it does

| Area | What you can do |
| --- | --- |
| Overview | Watch requests in flight, tokens per minute, success rate, time to first token, today's earnings and live models. Problems collect behind a **need attention** counter. |
| Endpoints | See each endpoint's models with their status, measured speed and prices. Open an endpoint to edit, publish and diagnose it. |
| Setup | Pick a source, connect with an API key or **Sign in with …** where the source supports it, discover models, choose public names, and set capacity and data policy. |
| Prices | Set exact per-model prices in USD, BTC or USD-indexed BTC, prefilled from [reference prices](/docs/providers/pricing#reference-prices-and-markup). |
| Publication | Review every change before you choose **Publish changes**. A failed capability check shows its cause and how to fix it. |
| Operation | **Start endpoint**, **Stop endpoint**, **Restart endpoint**, **Retry verification**, pause and resume. |
| Diagnostics | Run doctor checks and see the latest failed verification for each model, with the failed step and [how to fix it](/docs/providers/lifecycle#fixing-a-failed-check). |
| Activity | Read platform alerts about your endpoints and models, and the changes made from this app, grouped by day. |
| Earnings | See available and pending USD and BTC per account, daily earnings, the split by endpoint and model, and your withdrawals. **Withdraw** opens the web dashboard. |
| Machines | Manage this computer and remote Linux machines, their background services and agent updates. |

Every model is checked before publication. If some fail, the review lists each model's outcome and every failed model's report, and tags the failed models **Check failed**. **Publish N passing models** publishes the rest and keeps the failed ones for later with their settings. A model kept for later shows **Kept for later**; for a model that was already published, only its changes wait and its published terms stay as they are. **Include again** puts it back into the next publication, which checks it again.

**Publish changes** closes as soon as the platform accepts your submission; it doesn't wait for review. The app shows a notice when review finishes, and also a system notification if you turn on **Notify me about updates and operations needing attention** in Settings.

Live rates and session counters come from the running process. They're kept only while the app is open and are never used for earnings or routing.

## Naming your provider and endpoint

When you connect a source, choose the account under **Publish as**, then an existing **Provider** or **New provider (created on publish)** with a **Provider name**. Customers see the provider name; it must be unique within the account. **Endpoint name** identifies the endpoint and doesn't rename the provider.

Until the endpoint is registered, **Change provider** lets you correct the name or pick an existing provider without losing your model terms. If the name is taken by the time you publish, close the review and use **Change provider**.

## Reasoning mode

For sources whose capabilities are checked with live requests, **Edit terms** includes **Reasoning mode**:

- **Not advertised** removes the customer's reasoning control. It doesn't turn off the model's thinking.
- **Always on** declares that thinking can't be turned off.
- **Switchable** lets customers turn thinking on and off. Thinking on must pass publication checks. If the source still returns reasoning when it's turned off, publication continues and the review notes it; check the server's thinking switch and API dialect, or choose **Always on**.

Your choice survives a source refresh. Named cloud connectors keep their own reasoning settings.

During setup, a context length or maximum output your source didn't report is labelled **from catalogue** or **default** in the model list and in **Edit terms**, and a capability the catalogue lists but your source doesn't declare says **The catalogue lists it**. Choosing a name with **Search model names** fills limits that still hold a catalogue value or a default (see [limits your source doesn't report](/docs/providers/sources#limits-and-capabilities-your-source-doesnt-report)).

## Required prices

New USD-indexed Bitcoin rates, and rates affected by a change of pricing mode, need an explicit entry. When you review publication with unfinished rates, the app opens **Edit terms** at the first affected model and field. Enter each rate, including an explicit `0` where you intend it, then review again.

## Remote machines

The **Machines** view lists this computer and the remote machines you add, with their last contact, number of endpoints, installed and available agent versions, and the result of the last update.

The app connects to remote Linux machines with your system's OpenSSH and strict host-key checking. A remote machine needs GNU libc, the standard core utilities, OpenSSH with SFTP, and `flock` from util-linux. On first connection the app can install the agent for your user, in the same layout the installer uses. An existing installation is inspected, not overwritten.

Background reconnects never prompt. If a machine needs a password, passphrase or other answer, it shows **Needs sign-in or reconnect**, and prompts appear only after you choose **Connect**.

The app talks to the agent over local pipes, or over the SSH session for remote machines; the agent never opens a network port for it. Passwords and codes you type are never recorded. **Restart management process** replaces only this connection, for example after an agent update; it never restarts endpoints.

## User services

An endpoint started from a terminal stops at reboot. The app can install it as a per-user service instead:

| Platform | Service | Starts |
| --- | --- | --- |
| macOS | A LaunchAgent in your user account | When you sign in to macOS |
| Linux | A systemd user service | At boot, when lingering is enabled for your user |

Open an endpoint's **Background service** panel to set this up and choose automatic startup. The panel lists the environment variables the endpoint needs, for example for an `env://` API key, and stores only the values you enter in the profile's owner-only secret store. These are the same services that `numes provider service install` creates, and the app never overwrites a service it didn't create. Installing one also installs the agent's [updater](/docs/providers/install-and-update#automatic-updates).

**Restart endpoint** stops accepting new requests, lets running ones finish and restarts the endpoint. If draining takes too long, the restart is deferred. Restarting never publishes pending changes.

## Updates

The app and the agents it manages update separately.

**App updates.** The app checks for a signed update at launch and regularly afterwards, downloads it in the background and offers **Update and restart**. You can turn on **Automatically install and restart when idle**, which installs only inside your maintenance window and never interrupts open edits, pending operations, SSH sign-ins or agent updates.

- macOS: move the app from its DMG into Applications first. An app running from the disk image can't update itself.
- AppImage: keep the file executable, in a location you own and can write to.
- DEB and RPM: update through your package manager.

**Agent updates.** **Check for updates** asks a machine's agent to check its release feed, and **Update now** installs an available release. Each machine's **Install agent updates when idle** setting sets `auto_apply` in its [update policy](/docs/providers/install-and-update#update-policy). Agent updates follow the [usual update process](/docs/providers/install-and-update#automatic-updates). A failed or rolled-back update waits for you to retry it.

## Application server

**Settings › Application server** shows the server the app connects to. Changes are written to the `[application]` section of the shared `config.toml` on this computer, so the `numes` command uses the same server; see [the optional configuration file](/docs/providers/profiles#the-optional-configuration-file). Changing it requires a new sign-in. Remote machines keep their own settings.

## Interrupted operations

If the app or a connection stops before the outcome of a change is known, the operation is marked as uncertain. In **Activity**, review it against the current state of the endpoint and acknowledge it; acknowledging never repeats the action. Unreviewed operations block automatic updates.

An interrupted publication keeps its exact terms and must be retried or checked before further edits. If the source changed, choose **Refresh from source**, review the preview and publish again; your prices, context and concurrency settings are kept.

## Next steps

:::cards
- {rocket} [Provider quickstart](/docs/providers/quickstart) The same setup from the command line.
- {terminal} [Terminal UI](/docs/providers/terminal-ui) The keyboard workspace built into the agent.
- {tree} [Profiles and configuration](/docs/providers/profiles) Where desktop-managed endpoints keep their state.
- {shield} [Provider security](/docs/providers/security) How keys and connections are protected.
:::