Install Guardrino in four steps

Before you start

Guardrino is designed as a single small program that runs as a gateway with an OpenAI-compatible API. Your apps send their requests to Guardrino instead of straight to the model provider; Guardrino checks each message and forwards it. The package arrives from HisnLabs with your pilot and carries everything it needs, models included.

Step 1 · Install

Check the package first, then install it. Pick the way that suits your server.

Linux

The installer puts the program in /opt/guardrino, creates a guardrino system user and a systemd service.

sha256sum -c guardrino-<version>.sha256
tar xzf guardrino-<version>-linux-x86_64.tar.gz
cd guardrino-<version>
sudo ./install.sh

Linux, in a container

The same package also holds a container image, for servers that run Docker.

docker load -i guardrino-<version>-image.tar
docker run -d --name guardrino --restart unless-stopped \
  -p 8080:8080 \
  -v /etc/guardrino:/etc/guardrino \
  --env-file /etc/guardrino/guardrino.env \
  guardrino:<version>

Windows

In PowerShell as Administrator. The installer adds a Windows service named Guardrino.

# PowerShell, run as Administrator
Get-FileHash .\guardrino-<version>-x64.msi -Algorithm SHA256
# Compare the hash with the value HisnLabs gives you, then:
msiexec /i guardrino-<version>-x64.msi /qn

Step 2 · Configure

Everything Guardrino does is set in one policy file: /etc/guardrino/guardrino.toml on Linux, C:\ProgramData\Guardrino\guardrino.toml on Windows. Start in observe mode: Guardrino records what it would do and changes nothing.

mode = "observe"                # watch only: nothing is blocked while you tune
port = 8080

[upstream]
url = "https://llm-provider.example/v1"   # your model provider or model server
api_key_env = "UPSTREAM_API_KEY"          # the key is read from the environment, never written here

[l1]                            # rules layer
personal_data = "mask"
secret = "block"

[l2]                            # classifier layer
action = "block"
on_error = "allow"

upstream is where your requests go today: your model provider or your own model server. Its key stays in your environment or your own secret store, never in the policy file.

# Readable by the guardrino service only
sudo install -m 600 -o guardrino /dev/null /etc/guardrino/guardrino.env
echo 'UPSTREAM_API_KEY=<your provider key>' | sudo tee /etc/guardrino/guardrino.env > /dev/null

[Environment]::SetEnvironmentVariable('UPSTREAM_API_KEY', '<your provider key>', 'Machine')

Categories, thresholds and actions in the developer reference

Step 3 · Start and check

Start the service and ask it how it is.

sudo systemctl enable --now guardrino
curl http://localhost:8080/health

Start-Service Guardrino
Invoke-RestMethod http://localhost:8080/health

An illustrative answer:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "ok",
  "version": "<version>",
  "mode": "observe",
  "policy": "loaded",
  "model": "guardrino-t7-2610"
}

Step 4 · Connect your app

Change one line: the base URL. Your prompts, models and the rest of your code stay as they are. guardrino.internal stands for the name of the Guardrino server on your network.

from openai import OpenAI

# The only change: the base URL points at Guardrino instead of the provider.
client = OpenAI(base_url="http://guardrino.internal:8080/v1")

reply = client.chat.completions.create(
    model="<your-model>",
    messages=[{"role": "user", "content": "Hello"}],
)

import OpenAI from 'openai'

// The only change: the base URL points at Guardrino instead of the provider.
const client = new OpenAI({ baseURL: 'http://guardrino.internal:8080/v1' })

const reply = await client.chat.completions.create({
  model: '<your-model>',
  messages: [{ role: 'user', content: 'Hello' }],
})

curl http://guardrino.internal:8080/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "<your-model>", "messages": [{"role": "user", "content": "Hello"}]}'

Allowed messages go through unchanged, masked ones go through with the personal data replaced, and a refused message comes back as a clear refusal your app can show. The decision fields are described in the developer reference. Where the provider key lives is your choice: your apps can keep sending it, or it can stay with Guardrino only, so apps never hold it.

Responses in the developer reference

Running your own model server? See vLLM, Kubernetes, OpenShift AI and more

Watch, then enforce

Let Guardrino watch real traffic in observe mode first. The audit log shows, for every message, what it would have masked, warned about or blocked, so you can tune the policy before anyone is affected. When you are happy with what you see, switch one line and restart.

mode = "enforce"                # was "observe"

sudo systemctl restart guardrino
# or, in a container:
docker restart guardrino

Restart-Service Guardrino

Updates, offline

• Updates come from HisnLabs as signed bundles, models included. The installer checks the signature and refuses a bundle that does not match.
• You apply an update the same way you installed: check it, run the installer. Your policy file and audit log are kept.
• Nothing needs an internet connection: bundles can be carried into an air-gapped network.

Uninstall

Removing Guardrino keeps your policy file and audit log unless you delete them too.

sudo /opt/guardrino/uninstall.sh
# or, in a container:
docker rm -f guardrino

# Optional: remove the configuration and the audit log too
sudo rm -r /etc/guardrino /var/log/guardrino

msiexec /x guardrino-<version>-x64.msi /qn
# Optional: remove the configuration and the audit log too
Remove-Item -Recurse C:\ProgramData\Guardrino

Then point your apps back at their previous base URL.