Navin SM

The Navin SM page (/admin/navin-sm) gives the Navin desktop and CLI to your staff: it authors the organization file each workstation reads, keeps the packages of the release to distribute, issues the LiteLLM virtual keys of the staff and tracks their usage. Navin SM runs on no node of the cluster: it is a workstation software (catalog service navin-sm, delivery "Distribute to Workstations") that talks only to the LiteLLM gateway of the organization. The Profiles and Distribution tabs need settings:manage; choosing the vault entry of a shared key or of a GitHub token also needs vault:manage; the Access and Tracking tabs need navin_sm:keys (roles admin and security_admin). The routes are described in the API reference, tag navin-sm.

The four tabs

Tab	What it does	Permission
Profiles	one line per organization: name and identifier, gateway, authentication, models and default model, Exclusive or not, Linked to the installed LiteLLM service. Editor, Preview, Export, Download bundle per system, Delete	settings:manage
Distribution	the release of Navin SM the catalog names, its packages (published SHA256, stored copy, size, Download), Load SHA256SUMS, Upload a package, Fetch from GitHub, the last fetches and the deployment paths	settings:manage (vault:manage for GitHub)
Access	the LiteLLM virtual keys of a profile: assignee, status, models, budget, limits; Issue a key, Edit limits, Block, Unblock, Revoke, Revoke all	navin_sm:keys
Tracking	spend, tokens, calls, errors and last use of the keys of a profile over a period, per key and per model, read from the proxy	navin_sm:keys

Every save, export, discovery, package upload and key operation is written to the audit log (navin_sm.*, navin_sm.key.*, navin_sm.package.*), refusals included, never with a key or a token.

Profiles

A profile is the managed-settings.json of the organization gateway contract (version 1): the organization (name of 120 characters at most, support contact of 200), the gateway (http or https address without /chat/completions, authentication, headers, certificate authority), 1 to 200 models (id of 200 characters at most, label of 120), the default model, the routes, the exclusive flag and the policy Navin enforces. These limits are those of the parser of Navin: a profile the Manager accepts is a file Navin accepts.

• Link to an installed LiteLLM takes the address of a LiteLLM service installed by the Manager and keeps the link (litellm_cluster_id, litellm_service). Discover then reads /v1/models and /model/info with the master key of the service, which stays in the server; without a link, type a virtual key used for this call only. The link is also what lets the Manager issue the virtual keys (Access tab) and read the tracking.
• Use the CA of the Manager points gateway.caBundle at /etc/navin/navin-sm-ca.pem, /Library/Application Support/Navin/navin-sm-ca.pem or C:\ProgramData\Navin\navin-sm-ca.pem, and the bundle ships the PEM; the preview and the export then need the target system. Exclusive with a typed CA path.
• Preview shows the file as the export will write it, checked against the contract, without its key (a shared key appears as the name of its vault entry), with the problems found and the paths of the file and of the CA for the chosen system. Nothing leaves the server: the preview is not audited.
• Export downloads the file; the shared key is read from the vault at this moment only.

Authentication of the gateway: Key of each user (user_key, each workstation enters the virtual key issued by the Access tab), Shared key (shared_key, one key for everyone, taken from the vault and written in the file at export time: deploy it with restricted permissions) or None (none, the proxy authenticates by network).

Distribution and deployment

The packages are the assets of the GitHub release the catalog names (repository Navinspire-ia/navin-sm, tag v<version>): RPM and DEB (desktop and CLI) for Linux, Apple silicon and Intel DMG for macOS, MSI (GPO, Intune) and setup.exe for Windows, CLI archives per system. A package is kept only when its SHA256 is the one published with the release; a different file is refused, removed and audited (navin_sm.package.store denied). At download time the Manager hashes the stored copy again: a file altered on its disk is removed and refused (navin_sm_package_corrupt, audit navin_sm.package.download denied); upload or fetch it again.

Two ways in:

1. Offline: Load SHA256SUMS (paste the lines <sha256> <filename> of the SHA256SUMS and .sha256 files of the release), then Upload a package file by file. Without a loaded published SHA256, give the SHA256 of the file with the upload.
2. From GitHub: Fetch from GitHub with a vault entry whose API key is a GitHub token that can read the repository. The Manager downloads the checksum files then every package not stored yet, each verified; the token stays in the server. The tab follows the fetch (running, done, failed) file by file.

The bundle of a profile (one button per system on the line of the profile) is a zip navin-sm-<org_id>-<os>.zip to treat as confidential (it may hold the shared key):

System	Bundle content	Deployment
Linux	README.md, managed-settings.json, navin-manager-ca.pem (when the CA of the Manager is shipped), install.sh (RPM or DEB found next to it), ansible/playbook.yml, ansible/inventory.ini	Ansible: ansible-playbook -i ansible/inventory.ini ansible/playbook.yml with the packages next to the bundle; or install.sh as root
macOS	README.md, managed-settings.json, navin-manager-ca.pem (when shipped), install.sh (DMG of the architecture of the Mac), mdm/README.md	MDM (Jamf Pro, Intune, Kandji, Mosyle): DMG package and install.sh as a post install script, or file distribution to /Library/Application Support/Navin/managed-settings.json
Windows	README.md, managed-settings.json, navin-manager-ca.pem (when shipped), install.ps1 (MSI), gpo/README.md	GPO: assigned software installation of the MSI and a Files preference to C:\ProgramData\Navin\managed-settings.json; Intune: Win32 app with install.ps1

Paths of the organization file: /etc/navin/managed-settings.json (Linux), /Library/Application Support/Navin/managed-settings.json (macOS), %ProgramData%\Navin\managed-settings.json (Windows). A file deployed with the rights of the system cannot be removed by the user and enforces the policy. Without an administrator deployment, each user imports the file in Navin, Settings > Organization > Import (or navin org import <file>): only the organization and the gateway apply then. Navin SM has no telemetry and no auto update: a new version is deployed the same way.

Access: the lifecycle of a key

The Access tab needs a profile linked to a LiteLLM installed by the Manager: every call to the proxy carries the master key of the service, read from the vault by the server.

1. Issue a key to a user of the Manager (search by name, display name or email) or to a group of the identity provider, with the models allowed (none checked: all those of the profile), a budget and its reset period (30d, 1mo), tokens and requests per minute. The proxy creates the key (/key/generate); its value is shown once: copy it and hand it over through a safe channel. The Manager keeps only the alias (navin-sm.<org_id>.<assignee>.<random>) and the sha256 of the key, never the key.
2. Edit limits changes models, budget and limits at the proxy (/key/update) then in the Manager.
3. Block (/key/block): the proxy refuses the key at once; Unblock makes it active again.
4. Revoke (/key/delete): the key is deleted at the proxy immediately and kept here as revoked, with its date. Revoke all does it for every active or blocked key of the profile in one call.

A key the proxy no longer knows is recorded as revoked and the action is refused (navin_sm_key_gone). Every operation is audited (navin_sm.key.create|update|block|unblock|revoke|revoke_all) with the id and alias of the key, never its value.

Tracking and its limits

The Tracking tab reads the proxy through the server, over the chosen period (1 to 366 days, 30 by default): for each key its state at the proxy (/key/info: spend, budget, reset, blocked, deleted), and over the period its calls, tokens, errors, models and last use (/spend/logs); the same figures per model and in total. The spend is the figure LiteLLM reports, in its unit.

• Tracking unavailable: when the profile is not linked, the master key is missing or the proxy is out of reach, the tab says so with the reason and shows no figure; zeros are never invented.
• 10000 rows cap: /spend/logs returns 10000 rows at most; beyond that, the tab reports that the figures of the period are a lower bound. Shorten the period for a complete reading.
• The logs are those of the proxy: a revoked key keeps its past calls, a key deleted at the proxy outside the Manager shows "deleted at the proxy".

Checked against LiteLLM

The test tests/test_navin_sm_litellm_real.py starts a real LiteLLM OSS 1.106.5 proxy with its PostgreSQL database and migrations, a random master key and a dummy model (mock_response, no upstream), then drives a key through the client of the Manager. It proves that:

• /key/generate accepts the body the Manager builds (models, budget, budget_duration, tokens and requests per minute, metadata) and that the sha256 of the key is the token LiteLLM stores in its table; the clear key is not there. A duplicate alias and a negative budget are refused (400); LiteLLM does not check the models of a key against its list, the Manager does;
• /key/update applies the new limits, and an explicit null removes them;
• after /key/block, the proxy refuses the key (401 on /v1/models and /v1/chat/completions); after /key/unblock, it accepts it again;
• /key/generate does not create the LiteLLM user of the assignee: /user/info answers 404 until /user/new has made it;
• /spend/logs returns a list of rows tied to the sha256 of the key; the refused calls are there too, with the status failure, and Tracking counts them as errors (a refusal outside a model, on /v1/models, is counted under its route);
• /key/delete deletes the known keys and returns the list asked, even with an unknown sha256 (404 only when none exists); a deleted key can still be read by /key/info with the status deleted, and any other call on it answers 404, which the Manager reads as "the proxy no longer knows the key".

Typical tasks

1. Give Navin to the staff with your gateway only. Profiles tab, New profile, Link to an installed LiteLLM, Discover, pick the models and the default one, keep Exclusive gateway on, Save, Preview for the target system, then Download bundle.
2. Store the packages. Distribution tab, Fetch from GitHub (or Load SHA256SUMS then Upload a package offline); put the downloaded packages next to the scripts of the bundle.
3. Give access to a person. Access tab, profile, Issue a key, copy the key, hand it over through a safe channel; the person enters it in Navin (mode user_key).
4. Remove an access. Access tab, Block (reversible) or Revoke; Revoke all when a team leaves or a key leaks.

To decide on the Navin side

Nothing below is implemented: it is a contract proposal for a workstation inventory, for the Navin team to decide. Today Navin has no telemetry and no auto update; the Manager knows of the workstations only what LiteLLM reports about the keys.

• What Navin would report (and nothing else): the organization identifier of the file read, the Navin SM version, system and architecture, the SHA256 of the managed-settings.json applied (to detect a stale file), the time of the last start. No conversation content, no project path, no key.
• To which endpoint: a Manager route to create, POST /api/v1/navin-sm/inventory (body {org_id, version, os, arch, settings_sha256, started_at}), whose address would be written in the organization file by a new key organization.inventoryUrl (version 2 of the contract, ignored by current Navin builds).
• With which identity: the virtual key of the workstation (mode user_key), presented to the Manager, which checks it with LiteLLM by its sha256; or, in mode shared_key or none, a workstation certificate issued by the CA of the Manager. Never the master key.
• Activation: opt in by the organization, in the profile (Workstation inventory off by default) and therefore in the deployed file; a Navin without that key sends nothing. The screen would show one line per workstation (last report, version, file up to date or not) and flag the workstations silent for more than 30 days.