Install and update

The provider agent is the numes command: one executable that contains the terminal UI, guided setup, the serving process and every provider command. It has its runtime built in, so the machine needs no Node.js, Python or other toolchain.

Supported platforms

A shell running under Rosetta on Apple silicon gets the Apple silicon build. The installer needs curl, tar, and sha256sum or shasum.

Install

curl -fsSL https://numes.ai/install | sh

To read the installer before running it, download it first:

curl -fsSL https://numes.ai/install -o install.shless install.shsh install.sh

The installer detects your platform, downloads the release over HTTPS, checks it against the release's SHA256SUMS file and stops without installing anything if it doesn't match. The executable then checks itself against the release manifest, installs itself and links the numes command. The installer never edits your shell startup files and sends no telemetry. If the command directory isn't on your PATH, it prints the line to add, for example:

export PATH="$HOME/.local/bin:$PATH"

Running the installer again on a machine that already has an installation works like numes update, including draining and restarting background services.

Installer options

Check the installation

numes version

version prints the release version and the exact build, for example 0.1.0 (source-0123…). numes help lists the top-level commands and numes provider help the provider commands. Then sign in and open the terminal UI with numes auth login and numes provider tui; the Provider quickstart continues from there.

Where files go

~/.local/share/numes/                    the installation├── current -> versions/<sha256>         the active release├── versions/<sha256>/                   installed releases, named by their SHA-256 digest└── update-check.json                    when updates were last checked, and what is available~/.local/bin/numes                       link to current/numes~/.config/numes/provider/                profiles, sign-in and the optional config.toml

XDG_DATA_HOME and XDG_CONFIG_HOME move the first and last directories; the layout is the same on macOS. There is one installation per user account, shared by the CLI and the desktop app together with its profiles and settings. See Profiles and configuration.

Updates

Update by hand

numes update --check   # report whether a newer release is availablenumes update           # install the newest release nownumes update --retry   # try a release that was rolled back on this machine again

update works only for an installation made by the installer or the desktop app. Any other copy of the executable says so and shows the install command.

Automatic updates

When you install a background service, from the CLI or the desktop app, the agent also installs a per-user updater: a systemd user timer on Linux or a LaunchAgent on macOS. It stays installed while at least one profile has a background service. It wakes regularly and checks the release feed when a check is due, every check_interval plus a random delay of up to check_jitter. If an earlier check, such as the one the terminal UI runs, already found a newer release, the updater installs it the next time it wakes.

With automatic installation on, which is the default, an update:

1. Downloads the new release and verifies it against the release manifest.

2. Stops each background service from accepting new requests and lets running requests finish, for up to drain_timeout.

3. Switches to the new release and restarts each service.

4. Checks that every service reconnects to the platform, and switches back to the previous release if one doesn't.

With automatic installation off, the updater only records that a release is available: numes update --check reports it and numes provider tui shows a notice. Nothing changes until you run numes update.

Profiles started without a background service, with numes provider profile start or --start, keep running their current release until you restart them. numes update lists each one it finds still running an earlier release.

Update outcomes

An update never cancels a running request and never publishes pending changes to your models or prices.

Update policy

The [updates] section of the optional ~/.config/numes/provider/config.toml controls updates. Every key is optional.

[updates]auto_apply = falsecheck_interval = "12h"

The NUMES_AUTO_UPDATE environment variable overrides auto_apply: 0 or false turns automatic installation off, 1 or true turns it on. The desktop app's Install agent updates when idle setting writes auto_apply for you.

Upgrade from retired token limits

You can keep using the released agent when the platform removes rolling token limits. Valid older model declarations are accepted for new registrations and existing connections; token budgets no longer control platform admission.

If you choose to install the new agent, prepare saved profiles first. Set auto_apply = false and check that the updater's environment doesn't force NUMES_AUTO_UPDATE=1 or true; NUMES_AUTO_UPDATE=0 also disables installation. Follow Updating profiles with retired token limits to finish pending publications, stop affected profiles and remove retired local fields. Keep private owner-only originals before editing. The backend upgrade does not require this agent upgrade or a coordinated provider outage. Update the desktop after its matching agent, since the new desktop can't manage an old agent's retired model fields.

If installation already rolled back because saved fields failed validation, prepare the stopped profiles, then run numes update --retry and verify they reconnect. Restore your automatic-update preference after the checks pass. Do not rewind the release feed or discard pending publication evidence.

Release integrity

Every release has a manifest that names its version, its build, an increasing sequence number, an expiry time and, for each platform, the download address, SHA-256 digest and size. The agent downloads releases only over HTTPS, and refuses a manifest that has expired or is older than one it already accepted, and an executable whose digest or size differs from the manifest.

Minimum agent version

The platform may require a minimum agent version. An older agent is refused when it connects, with the reason agent_update_required. Run numes update, or let the updater install the current release.

When it connects, the agent reports its release version and build so our team can investigate problems. The report contains no local paths, device names or API keys.

Uninstall

numes uninstall

This removes the background service of every profile, the updater, the numes command link and every installed release. Your profiles, sign-in and local state in ~/.config/numes/provider/ stay, so a later installation picks up where you left off. So do the inference key and sessions kept by numes run.

To remove those too:

numes auth logoutnumes uninstall --purge --confirm

--purge deletes your profiles with their endpoint keys and source secrets, your saved sign-in, and the inference key and sessions of numes run; it requires --confirm. A purged inference key stays valid until you revoke it in Keys, and numes auth logout revokes your sign-in. Uninstalling never deletes anything on the platform: your provider, endpoints, offers, earnings and withdrawal history remain, and the endpoints show as offline. To serve an endpoint again from a new installation, use Reconnect agent.

Offline installation

For a machine that can't reach the release origin, copy the release archive for its platform and the release's SHA256SUMS file from another machine. Both are published under https://releases.numes.ai/numes/<version>/, and archives are named numes-<version>-<target>.tar.gz, where the target is linux-x64, linux-arm64 or darwin-arm64. Older releases may be removed from the release origin, so keep a copy of any version you may need to reinstall.

Compare the archive's digest with its line in SHA256SUMS, then install it with the installer script:

sha256sum numes-0.1.0-linux-x64.tar.gz      # macOS: shasum -a 256 FILEgrep numes-0.1.0-linux-x64.tar.gz SHA256SUMSsh install.sh --binary ./numes-0.1.0-linux-x64.tar.gz

A local archive comes without a release manifest, so checking the digest yourself is the integrity check. It's refused when a different release is already installed; use numes update, or run numes uninstall first. Once the machine can reach the release feed, the next release replaces it through the normal update process.

Next steps