User Guide — LINUS-AI

Installation

LINUS-AI ships as a single self-contained binary with no runtime dependencies. Download the appropriate build for your platform, mark it executable, and place it on your PATH. That's all there is to it.

System Requirements

Linux (x86_64 & ARM64)

v4.0.0 ships headless CLI binaries for Linux, macOS, and Windows. CUDA-enabled builds include GPU support out of the box. After install, consider setting up a systemd service for automatic startup on Linux. GUI installers (DMG / NSIS) are available on the Download page.

systemd Service (Linux)

To run LINUS-AI automatically on boot as a background server, create a systemd unit file. Replace your-user with your actual Linux username.

License Activation

LINUS-AI includes a 30-day free trial. After that, a license is required. Licenses are issued in the format LNAI-XXXX-XXXX-XXXX-XXXX and delivered to the email address used at checkout.

30-Day Trial

No action is required to start the trial. On first launch, LINUS-AI automatically enters trial mode. A banner is displayed at startup showing the remaining trial days. All features available on the Community plan are accessible during the trial.

CLI Activation

Activate with your license key and the email address used at purchase. An internet connection is required only for the initial activation handshake. After that, the binary operates fully offline.

Config File Activation

You can also add the license key directly to the configuration file. This is convenient for automated deployments or when managing multiple machines.

Environment Variable

For CI/CD pipelines or containerised deployments, supply the key via an environment variable. The email is not required when using the environment variable method after the initial machine binding has been completed.

Check License Status

Trial Expiry

When the 30-day trial expires, LINUS-AI enters read-only mode. Existing conversations in the vault remain accessible, but new inference requests are blocked until a valid license key is activated. The control panel GUI continues to load and will display an activation prompt.

Machine Binding (Perpetual Licenses)

Perpetual licenses are bound to the machine on which they are first activated. The binding uses a hardware fingerprint derived from CPU serial, motherboard UUID, and primary network interface MAC address. Virtual machines generate stable fingerprints. Each seat in your license can be bound to one machine at a time.

Deactivate & Move to Another Machine

To move a license seat to a new machine, deactivate it on the current machine first. This releases the machine binding and allows activation on a different device.

Model Management

LINUS-AI uses the Ollama model registry for downloading and managing models. Models are stored locally in ~/.linus_ai/models/ and are never uploaded or shared. Once downloaded, models work fully offline.

Pulling, Listing, and Deleting Models

Quantization Levels

Quantization reduces model size and memory usage at a small cost to output quality. Q4_K_M is the recommended default for most users — it offers an excellent balance of speed, memory, and quality.

Recommended Models

All models below are available from the Ollama registry. Pull them with linus-ai --pull-model <name>.

Inference Modes

LINUS-AI automatically selects the best inference backend for your hardware. You can override this with the backend config key or the --backend CLI flag.

Backend Detection Output

GPU Layers

The gpu_layers setting controls how many model layers are offloaded to the GPU. -1 offloads all possible layers (maximum GPU acceleration). Reduce this number if you hit out-of-memory errors.

CPU Threads

CPU thread count is automatically detected from your system's logical core count. Override it with threads = N in config or --threads N on the command line. For best performance, set threads to the number of physical (not logical) cores.

Context Length

Context length (in tokens) determines how much conversation history and document content can be kept in a single inference pass. Larger contexts use more memory. Supported models (e.g., Qwen2.5, Llama 3.1) support up to 128K tokens.

AI Profiles

AI Profiles are pre-tuned system prompt configurations optimised for specific industry verticals and use cases. Each profile shapes the model's behaviour, tone, terminology, and response style without requiring any prompt engineering on your part.

Available Profiles

Each profile operates under one of four compliance tiers that govern PII handling, consent requirements, and audit logging. The tier is displayed alongside the profile in the GUI and CLI.

Compliance & Consent

Profiles in the REGULATED and RESTRICTED tiers require a one-time acknowledgement before first use on each machine. When you first activate one of these profiles, a consent dialog appears with the full legal disclaimer specific to that profile's regulatory context. You must scroll through and explicitly accept before proceeding. Your acceptance is stored locally per-machine per-profile in ~/.linus_ai/consents/ — you will not be prompted again on the same machine unless the disclaimer is updated.

PII Detection & Handling

All prompts in AUDIT, REGULATED, and RESTRICTED profiles are scanned for personally identifiable information before being sent to the model. PII is classified into two categories:

Prompt Injection Detection

LINUS-AI scans all incoming prompts for injection patterns — attempts to override system instructions, exfiltrate context, or manipulate the model's role. Detected attempts are flagged and recorded in the audit log. On the Security (security) profile, a detected injection attempt causes the request to be immediately blocked and the session to be suspended pending review.

Audit Logging

All activity in AUDIT, REGULATED, and RESTRICTED profiles is written to a tamper-evident audit log at ~/.linus_ai/audit/. Each log entry is HMAC-chained to the previous entry — any modification, deletion, or reordering of records breaks the chain and is detected on next verification. Log entries include timestamp, user identity, profile, model, PII scan results, consent status, and (for non-blocking PII) the redaction map.

Document Access Control (RAG)

When you upload documents for Retrieval-Augmented Generation (RAG), each document is automatically registered in the RAG registry with a classification level. Access decisions are enforced per-user at query time — you only receive content from documents you are authorised to access.

Document Classification Levels

Access Decision Factors

Each RAG retrieval call performs a per-document access check against the requesting user's identity attributes: department, division, company, roles, and clearance level. Documents that the user is not authorised to access are silently withheld from the retrieved context — the response is generated only from documents the user can see. No indication is given to the user that additional documents exist but were withheld.

All access decisions — both grants and denials — are recorded in the RAG audit trail at ~/.linus_ai/audit/rag/. This trail is also HMAC-chained for tamper-evidence and can be verified with linus-ai --rag-audit-verify.

Selecting a Profile

Custom System Prompts

Every profile ships with a carefully crafted default system prompt. You can override it at any level — globally via config, per-request via the API, or interactively in the GUI — without affecting the profile selection for other sessions.

Override via GUI

Open the control panel at http://localhost:8080, navigate to the Setup tab, and find the System Prompt Customization card. Edit the text area and click Save. The override is stored per-profile in your browser's localStorage, so each profile remembers its own custom prompt independently. Click Reset to Default at any time to restore the profile's built-in prompt.

Override via API

Pass a system field in the request body when calling POST /agent/stream or the OpenAI-compatible POST /v1/chat/completions endpoint.

Override via Config File

Set a global system prompt in ~/.linus_ai/config.toml. This applies to all CLI and API requests that do not supply their own system field. Profile-level prompts take precedence over this global setting unless you explicitly set the profile to none.

Control Panel GUI

LINUS-AI includes a built-in web control panel. Start it with linus-ai --serve and open http://localhost:8080 in any modern browser. No additional installation or configuration is needed.

CLI Reference

All flags can also be set via ~/.linus_ai/config.toml or environment variables. CLI flags take highest precedence, followed by environment variables, then the config file.

Troubleshooting

Common issues and their solutions. If you cannot find a fix here, check the log file at ~/.linus_ai/logs/linus-ai.log and include the relevant excerpts when reporting an issue.

Log Location

Detailed logs are written to ~/.linus_ai/logs/linus-ai.log. The log rotates daily and keeps 7 days of history. Pass --verbose at startup to increase log verbosity for debugging. When reporting an issue on GitHub, please include the last 50 lines of the log.