# Install and update

> Install the numes command, keep it updated automatically or by hand, roll back, uninstall and install offline.

Source: https://0.0.0.0:3000/docs/providers/install-and-update
Documentation index: https://0.0.0.0:3000/docs/llms.txt

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

| Platform | Supported |
| --- | --- |
| Linux x64 (glibc) | Yes |
| Linux ARM64 (glibc) | Yes |
| macOS on Apple silicon | Yes |
| musl-based Linux such as Alpine, Intel Macs, Windows | No. The installer refuses them. |

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

## Install

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

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

```bash
curl -fsSL https://numes.ai/install -o install.sh
less install.sh
sh 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:

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

Running the installer again on a machine that already has an installation works like [`numes update`](#updates), including draining and restarting background services.

### Installer options

:::fields Options

- `--version` `string` — Install this release instead of the latest stable one, for example `curl -fsSL https://numes.ai/install | sh -s -- --version 0.1.0`.
- `--binary` `path` — Install from a release archive you already downloaded. See [Offline installation](#offline-installation).
- `NUMES_INSTALL_DIR` `environment` default `~/.local/bin` — Directory for the `numes` command link.
- `NUMES_RELEASE_ORIGIN` `environment` — Download releases from another HTTPS origin, such as a mirror that copies the official release files unchanged.
  :::

## Check the installation

```bash
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](/docs/providers/quickstart) continues from there.

## Where files go

```text
~/.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](/docs/providers/desktop) together with its profiles and settings. See [Profiles and configuration](/docs/providers/profiles).

## Updates

### Update by hand

```bash
numes update --check   # report whether a newer release is available
numes update           # install the newest release now
numes 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](/docs/providers/quickstart#keep-it-running), 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

| Outcome | What happened | What to do |
| --- | --- | --- |
| Installed | The new release is active and every service reconnected. | Nothing. |
| Deferred | Running requests didn't finish within `drain_timeout`. The previous release kept serving. | Nothing; the next check tries again. |
| Rolled back | The new release didn't start or reconnect, so the previous release was restored. | It isn't retried automatically. Check `numes provider status` and the profile log, then run `numes update --retry`, or wait for the next release. |
| Needs recovery | The update couldn't complete or be undone cleanly. | Run `numes provider status` and follow the next action. |

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.

:::fields [updates]

- `auto_apply` `boolean` default `true` — Install new releases automatically. `false` only reports them.
- `check_interval` `duration` default `"6h"` — Time between release checks, from `1h` to `7d`.
- `check_jitter` `duration` default `"30m"` — Largest random delay added to each check, up to `24h`.
- `drain_timeout` `duration` default `"10m"` — How long running requests may take before an update is deferred, from `10s` to `1h`.
- `manifest_url` `string` — The HTTPS release feed. Change it only to follow a different channel or a mirror.
  :::

```toml title="~/.config/numes/provider/config.toml"
[updates]
auto_apply = false
check_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](/docs/providers/profiles#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

```bash
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`](/docs/integrations/coding-agents#what-is-stored-where).

To remove those too:

```bash
numes auth logout
numes 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](/dashboard/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](/docs/providers/lifecycle#reconnecting-the-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:

```bash
sha256sum numes-0.1.0-linux-x64.tar.gz      # macOS: shasum -a 256 FILE
grep numes-0.1.0-linux-x64.tar.gz SHA256SUMS
sh 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

:::cards

- {rocket} [Provider quickstart](/docs/providers/quickstart) Sign in, connect a source and publish your first model.
- {console} [CLI reference](/docs/providers/cli) Every command, including `service`, `update` and `uninstall`.
- {tree} [Profiles and configuration](/docs/providers/profiles) Where profiles live and what the optional configuration file can change.
- {monitor} [Desktop app](/docs/providers/desktop) Manage installations and updates on this and remote machines.
  :::