# Profiles and configuration

> How the provider agent stores each endpoint as a profile, what the profile and configuration files contain, how secrets are referenced, and how to run several profiles.

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

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.

| You want to | Do this |
| --- | --- |
| Serve Ollama and an upstream API account from one machine | Two profiles, one per source |
| Serve two vLLM servers on different GPUs | Two profiles with different `--source-url` values |
| Add a model to a source you already serve | Add it to the existing profile in the terminal UI or desktop app |
| Serve under another provider name | A new profile, with `--provider-name` or `--provider` |
| Reuse the provider of an existing profile for a new source | `setup SOURCE --reuse-provider-from PROFILE` |

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](/docs/providers/install-and-update#where-files-go).

```text
~/.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.

:::fields [control]
- `endpoint_id` `string` required — The endpoint this profile serves. Don't change it.
- `credential_secret` `string` default `"local://transport-enrollment"` — Secret reference for the endpoint key.
- `maximum_concurrent` `integer` — Local limit on simultaneous requests. It can lower, but never raise, the capacity you published.
- `maximum_request_duration` `duration` default `"11m"` — Longest a single request may run.
- `drain_timeout` `duration` default `"30s"` — On stop or restart, how long running requests may take to finish.
:::

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

:::fields [backend]
- `kind` `string` required — Source kind, such as `ollama` or `vllm`.
- `base_url` `string` required — The source's API address.
- `auth_mode` `string` default `"none"` — `none`, `api_key` or `oauth`.
- `api_key_secret` `string` — Secret reference for the source API key.
- `oauth_state_secret` `string` — Secret reference for browser sign-in state, for sources that support it.
- `dialect` `string` default `"auto"` — `auto`, `responses`, `messages`, `gemini` or `compatible`.
- `catalog_path` `string` default `""` — Path to a reviewed [catalog overlay](/docs/providers/sources#catalog-overlays).
- `prompt_cache_policy` `string` default `"automatic"` — `automatic` adds cache control for OpenRouter and Anthropic-style sources when the customer sent none; `explicit` forwards only the customer's own directives.
- `request_timeout` `duration` default `"11m"` — Timeout for each source request.
:::

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:

```bash
numes provider config path --profile NAME       # where the file is
numes provider config show --profile NAME       # contents, secrets redacted
numes provider config validate --profile NAME   # parse and check that secrets resolve
numes 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](/docs/providers/desktop) reads and writes the same file on this computer.

:::fields [application]
- `api_base_url` `string` — The platform's API origin.
- `oidc_issuer` `string` — The identity service used for sign-in.
- `loopback_client_id` `string` — Sign-in client for browser sign-in on this machine.
- `device_client_id` `string` — Sign-in client for device-code sign-in.
- `api_audience` `string` — Audience of the sign-in tokens.
- `login_method` `string` default `"auto"` — Default sign-in method: `auto`, `loopback` or `device`.
- `login_timeout_seconds` `integer` default `600` — Sign-in timeout, between 30 and 900. Also applies to source sign-in.
- `access_token_secret` `string` — An `env://NAME` reference to a token for headless automation. A plaintext token is never accepted.
:::

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.


:::fields [provider_defaults]
- `maximum_concurrent` `integer` default `100` — Endpoint concurrency proposed for new profiles.
- `submission_review_poll_interval` `duration` default `"5s"` — How often the terminal UI refreshes submissions in review, between 1 and 60 seconds.
- `source_probe_timeout` `duration` default `"10m"` — Time limit for model discovery during setup, at most one hour.
:::

The `[updates]` section is described in [Update policy](/docs/providers/install-and-update#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.

```toml title="~/.config/numes/provider/config.toml"
[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`:

```bash
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:

| Variable | Effect |
| --- | --- |
| `NUMES_PROFILE_ROOT` | Profile root directory. |
| `NUMES_APPLICATION_CONFIG_PATH` | Configuration file, when `--application-config` isn't given. |
| `NUMES_AUTO_UPDATE` | Overrides `[updates] auto_apply`: `0` or `false` turns automatic updates off, `1` or `true` turns them on. |
| Variables named by `env://` references | Source API keys and other secrets you keep in the environment. |

## Secret references

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

| Reference | Meaning |
| --- | --- |
| `env://NAME` | Read from the environment variable `NAME` when needed. Read-only. `NAME` is uppercase letters, digits and underscores, starting with a letter. |
| `local://NAME` | Read from the profile's owner-only `secrets/` store. Setup writes these for keys you type and for the endpoint key. |

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.

```bash
numes provider profile list                           # local profiles
numes provider profile start --profile NAME           # start in the background
numes provider profile start --all                    # start every saved profile
numes provider profile status --profile NAME          # local runtime state
numes provider profile status --profile NAME --ready  # exit non-zero until ready
numes provider doctor --profile NAME                  # diagnose a profile
numes provider stop --profile NAME                    # drain and stop
numes 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](/docs/providers/quickstart#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](/docs/providers/lifecycle#pausing-and-stopping).

### 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

```bash
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](/docs/providers/lifecycle#reconnecting-the-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](/docs/providers/install-and-update#update-policy) 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

:::cards
- {plug} [Inference sources](/docs/providers/sources) Source kinds, addresses, dialects and catalog overlays.
- {shield} [Provider security](/docs/providers/security) How keys, sign-in and the connection are protected.
- {console} [CLI reference](/docs/providers/cli) Every `profile`, `config` and `capacity` option.
- {terminal} [Terminal UI](/docs/providers/terminal-ui) Manage profiles interactively.
:::