Profiles and configuration

The agent keeps everything it needs to serve one endpoint in a profile: the source connection, the endpoint binding, the endpoint key and the local runtime state. Setup, the terminal UI and the desktop app write profiles for you; the layout matters for automation, backups and troubleshooting.

One profile, one source, one endpoint

A profile serves exactly one inference source through exactly one endpoint, and runs as its own process with its own connection to the platform.

Profile names start with a letter or digit and may contain letters, digits, ., _ and -, up to 64 characters.

Where state lives

The profile root is ${XDG_CONFIG_HOME:-~/.config}/numes/provider. Override it with the NUMES_PROFILE_ROOT environment variable or --profile-root PATH on any command. The installed executable lives separately; see Install and update.

~/.config/numes/provider/├── config.toml                    optional settings that override built-in defaults├── profiles/│   └── <profile>/│       ├── profile.toml           profile configuration│       ├── profile.json           model selection, prices and platform binding│       ├── provider.log           operational log│       ├── secrets/               owner-only local secret store│       └── runtime/control.sock   local control socket while running├── setup-drafts/                  resumable setup drafts└── human-auth/                    your sign-in

Every directory and file is owner-only. The agent refuses a directory that other users can read, that is a symbolic link, that someone else owns, or that sits inside a Git repository. Edits are validated before they replace a file, so a failed edit keeps the last valid configuration.

The log contains no prompts, responses or keys. numes provider logs --profile NAME prints its path. Each JSON line includes a UTC timestamp. Disconnect events identify the session slot, a fixed transport reason and, when available, a numeric gRPC status, even while another session remains connected. Native error messages and private addresses stay out of the log.

The profile file

Setup writes profile.toml. These are the settings you might change; leave the rest as setup wrote them.

When updating an older profile, remove generation_retention from [control] and any PROVIDER_GENERATION_RETENTION override. These settings are no longer supported.

The [runtime] section and the connection settings in [https] and the rest of [control] are set by setup; don't change them.

Existing profiles keep their saved timeout values when the executable updates. To serve requests lasting up to 10 minutes, set both maximum_request_duration and request_timeout above 10 minutes. The upstream service may impose its own shorter limit.

Durations are strings such as "500ms", "30s" or "10m". Inspect and edit the file with the config commands:

numes provider config path --profile NAME       # where the file isnumes provider config show --profile NAME       # contents, secrets redactednumes provider config validate --profile NAME   # parse and check that secrets resolvenumes provider config edit --profile NAME       # open in $VISUAL or $EDITOR

config edit validates the file after your editor exits and restores the previous version if it's invalid. Editing the file never publishes anything; published terms change only through setup, the terminal UI or the desktop app.

The optional configuration file

The agent works without a configuration file: built-in defaults connect it to Numes. To change individual settings, create config.toml in the profile root and set only the keys you want to change.

Select a different file with --application-config PATH or the NUMES_APPLICATION_CONFIG_PATH environment variable; a file named that way must exist. The desktop app reads and writes the same file on this computer.

Leave the first five keys unset to use Numes. Set them together only when your organization runs its own deployment and gives you its values. Changing them requires a new sign-in.

The [updates] section is described in Update policy. The file also accepts a [pricing] section for the Bitcoin/USD quote used to suggest fixed Bitcoin prices; quotes are suggestions and never convert money.

[application]login_method = "device"​[updates]auto_apply = false

An invalid value or unknown key is rejected with an error that names the setting, and the command doesn't run. The agent never reads configuration from the current directory and never loads .env files.

Environment overrides

Named profiles treat their stored TOML as authoritative. PROVIDER_* overrides of profile settings, such as PROVIDER_MAXIMUM_CONCURRENT or PROVIDER_BACKEND_BASE_URL, are ignored unless you start the command or process with --allow-env-overrides:

PROVIDER_DRAIN_TIMEOUT=60s numes provider daemon --profile vllm --allow-env-overrides

numes provider config show --profile NAME --effective lists which override names are set and whether they're active, never their values. These variables always apply:

Secret references

Wherever the agent needs a secret, the configuration holds a reference, never the value.

Secrets the agent must rewrite, such as the endpoint key after Reconnect agent or browser sign-in state, need local://. Status output, config show, logs, exports and errors never print a resolved secret.

Running profiles

Each profile runs as one process, controlled through an owner-only socket in the profile's runtime/ directory; the agent never opens a network port for control. A second process for the same profile refuses to start.

numes provider profile list                           # local profilesnumes provider profile start --profile NAME           # start in the backgroundnumes provider profile start --all                    # start every saved profilenumes provider profile status --profile NAME          # local runtime statenumes provider profile status --profile NAME --ready  # exit non-zero until readynumes provider doctor --profile NAME                  # diagnose a profilenumes provider stop --profile NAME                    # drain and stopnumes provider daemon --profile NAME                  # run in the foreground

• profile start keeps running after the terminal closes, but not after a reboot. For that, install a background service; see Keep it running. Once a service is installed, profile start and stop control it.

• profile start --all skips running profiles, tries every other one, and exits non-zero if any fails. It can't be combined with --profile.

• profile status --ready succeeds only when the source is healthy, the platform connection is up, the published terms are accepted and the profile accepts requests. It doesn't show platform approval; use numes provider status for that.

• doctor checks configuration, secrets, source reachability, model changes, endpoint identity, enrollment, the platform connection and version compatibility.

Stopping and draining

Stopping a profile stops new requests and lets running ones finish for up to drain_timeout before it closes. A stopped profile shows as Offline; stopping isn't pausing. To take an endpoint out of routing deliberately, pause it.

Connection recovery

After your device sleeps or its network changes, the agent checks its platform connection and reconnects automatically. It can retry a failed connection before a request is accepted; accepted requests are never replayed.

Applying settings

Publishing new terms or changing local capacity in the terminal UI or desktop app reloads a running profile in place, without a manual stop and start. If the reload's checks fail, for example because a key is missing, the running process keeps serving and the failure is reported.

numes provider capacity edit --profile NAME --maximum-concurrent N changes the local limit of a running profile immediately. It doesn't change the capacity you published.

Removing a profile

numes provider profile remove --profile NAME --confirm

Removal first deletes the profile's endpoint on the platform: its offers stop serving and it can't be restored. Then it stops the process and deletes the local files. If the platform refuses the deletion, nothing changes. History, earnings and the provider itself stay. A profile that was never published has no endpoint, so only its local files are deleted.

To keep the endpoint and delete only the local files, add --keep-endpoint. The endpoint shows as offline until you delete it in the dashboard or reconnect an agent to it.

Updating profiles with retired token limits

The platform accepts valid legacy token-capacity declarations from released agents. You do not need to stop or upgrade an existing agent for the backend upgrade, and the released agent can register a new model.

Before choosing to install the new agent, turn off automatic installation and disable autopilot for each affected endpoint with numes provider autopilot disable --profile NAME, or choose Manual in the dashboard. Pause manual publication while preparing those profiles. Keep the current desktop until pending work is resolved, then update it after its matching agent. Use the current CLI or terminal UI for preparation.

Finish any frozen publication using the installed version, including checking whether an unconfirmed publication was accepted. Preserve pending work and accepted history. Let running requests finish, then stop affected profiles and their installed background services. Verify they're stopped before editing saved data, so an old process can't write the retired fields back.

Before editing, authorize and keep private filesystem copies of the affected application/profile TOML, profile JSON and setup draft JSON, retaining each profile's relative paths. Use cp -p into an owner-only directory (mode 0700) and check files remain mode 0600. Keep copies outside the repository and shared storage; don't copy sign-in stores or journals. They retain the exact removed values for restoring those fields if the upgrade is aborted before installation. Stop if this private restore path is unavailable.

Remove only promptTokenCapacity from model records in profile.json (selectedModels and recovery draft baseModels/localModels) and saved setup draft.json files (selectedModels only). Remove provider_defaults.input_token_context_multiplier from local configuration too. These retired fields fail validation and can appear as an unsafe-profile error; keep owner-only permissions and every other field intact. Once the accepted agent release is available, update and restart your profiles, check their release and connection, then resume publication and autopilot. If the update already rolled back, use numes update --retry after preparing the stopped profiles; it won't retry that release automatically. Restore your preferred automatic-update setting after these checks. Unchanged accepted profiles need no forced republication. Accepted models remain readable and editable; subsequent publications omit retired token capacity, including unchanged models. Context, per-request limits, prices and concurrency retain their existing rules. If preparation is aborted before installing the new agent, restore only the removed fields from your private copies, preserving subsequent recovery state. Then validate and restart with the original agent. An executable update retry is not a backend rollback; preserve release sequence and publication evidence.

Next steps