Docs / Security and deployment

Deploy and manage

Install Verbiqo the way you install other software, then set its AI service, embedding service, licence and switches centrally. Values you set are used on every computer and locked in Settings. Roll out to a team is the short version.

Install

Roll out to a team: the licence and the AI services

One settings file sets everything a team needs: the AI service, the embedding service for Prometheus, and the licence. Nobody is sent a file or a URL, and each person only ever types their own API key.

1. Write the settings

   Start from the template and keep what you need:

   {
     "organization": "Example",
     "provider": "openai",
     "endpoint": "https://ai-gateway.example.internal/v1/chat/completions",
     "model": "qwen3-30b-instruct",
     "sendApiKey": true,
     "embeddingEndpoint": "https://ai-gateway.example.internal/v1/embeddings",
     "embeddingModel": "qwen3-embedding",
     "embeddingUsesModelKey": true,
     "trustedCA": {
       "mac": "/Library/Application Support/Verbiqo/company-ca.pem",
       "windows": "C:\\ProgramData\\Verbiqo\\company-ca.pem"
     },
     "licensePath": {
       "mac": "/Library/Application Support/Verbiqo/team.verbiqo-license",
       "windows": "C:\\ProgramData\\Verbiqo\\team.verbiqo-license"
     }
   }

2. Build the files

   verbiqo policy settings build settings.json verbiqo-settings

   This writes the Mac profile, the Group Policy template, the Intune script and a .reg file (which is which).

3. Copy the CA and the licence file

   To the same paths on every computer, in a folder only administrators can change (how).

4. Push the settings

   Through Jamf, Intune, Kandji or Group Policy (Mac, Windows).

On each computer, within half a minute: the AI service and embedding service are set and locked, the licence is imported and takes a seat, and Settings shows Managed by your administrator. Each person enters their own LiteLLM key once in Settings; with embeddingUsesModelKey on, that one key covers the embedding service too. Check it on one Mac and one PC first: Test a deployment.

Managed settings: set and lock

Every value you set here is also locked. Settings shows it greyed out with Managed by your administrator, and the person cannot change it. Anything you leave out stays theirs to set. Locking comes from these values, not from the privacy policy; the policy is a separate check that refuses what it does not allow (which does what).

Set any of these and leave the rest to each person. On a Mac they go in a configuration profile for the preference domain com.verbiqo.app; on Windows, under HKLM\Software\Policies\Verbiqo (all users) or HKCU\Software\Policies\Verbiqo (one user). When both are set, the machine’s value wins.

The settings.json column is the name each setting has in the file the generator reads; the Mac and Windows columns are what it writes.

• An endpoint you set needs no confirmation from the person: the organization chose it. An Ollama server you name elsewhere on the network is allowed without the “remote” switch.
• A value out of range is ignored, never fatal: Verbiqo starts with the person’s own value and notes it in the diagnostic log.
• API keys, including the embedding service’s, are never set centrally: see API keys.
• The same settings can pin a privacy policy: Privacy policy.

Which provider to set

• Write the provider in lower case, exactly as shown; the same name on Mac and Windows.
• The endpoint is the full URL, path included. For an OpenAI-compatible server, one ending in /chat/completions is openai-chat-completions in the policy; any other is openai-responses.
• A privacy policy must name the same endpoint, character for character, and the same model (Privacy policy).

Make the files

One list of values gives every file both platforms need, so nothing is typed twice or misspelt. With the command line tool:

verbiqo policy settings template > settings.json
verbiqo policy settings build settings.json verbiqo-settings

In settings.json, keep only what you want set and locked; anything left out stays each person’s own. A file path can be one string, or { "mac": "…", "windows": "…" } where they differ. A misspelt name or a value out of range is refused with the fix. The folder then holds:

Push the settings to Macs

Push the settings to Windows PCs

A running Verbiqo picks up new or changed values within half a minute, on both platforms.

Copy the CA, policy and licence files

Settings only say where a file is: the CA file, a signed policy and its public key, and the licence file must be on each computer too. Verbiqo reads your CA from the file even if the computer already trusts it. Put them in one folder that everyone can read and only administrators can change: /Library/Application Support/Verbiqo on a Mac, C:\ProgramData\Verbiqo on Windows.

On Windows, also lock the folder: anyone can create folders under C:\ProgramData, so someone who made Verbiqo first could change what is in it. A script that writes the CA and does that:

$dir = 'C:\ProgramData\Verbiqo'
New-Item -ItemType Directory -Path $dir -Force | Out-Null
# Owned by Administrators, so whoever made the folder cannot change this back.
icacls $dir /setowner Administrators /T | Out-Null
icacls $dir /inheritance:r /grant:r 'Administrators:(OI)(CI)F' 'SYSTEM:(OI)(CI)F' 'Users:(OI)(CI)RX' /T | Out-Null
Set-Content -Path "$dir\company-ca.pem" -Encoding ascii -Value @'
-----BEGIN CERTIFICATE-----
(your CA, as PEM text)
-----END CERTIFICATE-----
'@

On a Mac, as root:

mkdir -p "/Library/Application Support/Verbiqo"
cp company-ca.pem policy-signed.json policy-public.pem team.verbiqo-license "/Library/Application Support/Verbiqo/"
chown -R root:wheel "/Library/Application Support/Verbiqo"
chmod 755 "/Library/Application Support/Verbiqo"; chmod 644 "/Library/Application Support/Verbiqo/"*

API keys

API keys are never part of the central settings. A key copied onto every computer can be read by anyone who uses those computers, so it stays neither secret nor tied to one person. Instead:

• No key: run the AI gateway on your network without one, reachable only from your computers, and pin it with a privacy policy. Set sendApiKey to false.
• A key per person: issue each person their own key at the gateway (LiteLLM calls these virtual keys), so usage and access are per person. Set sendApiKey to true: Verbiqo asks for the key, and each person enters it once in Settings, where it is kept in the Keychain or Credential Manager.

Different rules for different groups

Verbiqo has no sign-in of its own: your device management decides who gets which rules, the same way it targets any profile or policy.

1. One policy per group

   Sign a policy for each, with its own policyId and the same key. For example acme.dba allowing "pg" and "mysql", and acme.support allowing only "prom", each with its own features and limits.

2. Copy the files

   Put each group’s signed policy on its computers, or every policy on every computer under its own name, such as policy-dba.json and policy-support.json.

3. One settings file per group

   Each group’s settings.json names its policy file in policyPath and pins its ID in policyId, so a computer cannot be pointed at another group’s file. Build each with verbiqo policy settings build.

4. Target each group

   Assign each group’s files to it in your tool.

• Per person on Windows applies where no policy is set for the whole computer: a machine-wide policy wins over a user’s.
• A group with no access to any system: instead of a policy, set extensionsEnabled to false in that group’s settings, which hides Extensions entirely.
• To check a computer: verbiqo policy check on its policy file says what that group may do.

Licences for an organization

Deploy the licence like the CA file: copy it onto each computer and name it in the settings. Nobody is sent the file, nobody imports it, and Settings › Licence shows Managed by your administrator with Import and Deactivate turned off.

1. Copy the licence file

   Put your .verbiqo-license file in the protected folder with the other files: /Library/Application Support/Verbiqo/team.verbiqo-license on a Mac, C:\ProgramData\Verbiqo\team.verbiqo-license on Windows (how).

2. Name it in the settings

   Add licensePath to settings.json and build the files as above:

   "licensePath": {
     "mac": "/Library/Application Support/Verbiqo/team.verbiqo-license",
     "windows": "C:\\ProgramData\\Verbiqo\\team.verbiqo-license"
   }

3. Push both

   Each computer imports the file and, for a licence key, takes a seat at verbiqo.app: at launch, within half a minute of the settings arriving, and at every licence check after. A computer that cannot get a seat (all in use, or offline) tries again at the next check and keeps any licence it already had.

• Seats: one licence key with a number of seats; each computer holds one and renews it daily. A computer that has not checked in for 37 days frees its seat.
• See and free seats: whoever holds the licence key file can list the computers holding its seats, least recently active first, and free one:

  verbiqo licence seats team.verbiqo-license
  verbiqo licence free team.verbiqo-license hw-1234abcd

  Each computer is listed by its name on the licence (its computer name unless changed, or deviceLabel above), its device ID, and when it last checked in, to the minute. Each computer’s device ID is in Settings › Licence. Another computer’s seat can be freed once it has gone 7 days without checking in, so nobody takes the seat of someone who is working.
• Someone leaves: wipe or reassign their computer; its seat frees 7 days after it last checked in (or at once, with verbiqo licence free after those 7 days). The file sits on each computer readable by the person using it, as it must for Verbiqo to read it, so someone determined could copy it. If you think a copy left with someone, issue a replacement licence under a new ID, push it to the same path, and revoke the old one: every computer moves to the new licence by itself, and the copy stops working.
• A new licence, more seats, a renewal: replace the file at the same path. Computers pick it up at their next check.
• Computers that never reach the internet: a seat file listing each computer’s device ID, deployed the same way. Trial and licences