Configuration#

Nixi can be configured via CLI flags, environment variables, or config files.

Priority Order#

Configuration is loaded in this order (highest priority wins):

1. CLI flags – --url, --model, --api
2. Environment variables – NIXI_LLM_URL, NIXI_MODEL, etc.
3. User config – ~/.config/nixi/config.toml
4. System config – /etc/nixi/config.toml (written by the NixOS module)
5. Defaults

User config overrides the system config, so you can use the NixOS module for base settings and tweak per-user.

CLI Flags#

--url      LLM server URL (default: http://localhost:11434)
--model    Model name (default: qwen3:30b-a3b)
--api      API type: auto, ollama, openai (default: auto)
--version  Print version and exit

The serve subcommand accepts additional flags:

nixi serve [flags]
  --port   Web UI port (default: 6494)
  --host   Bind address (default: 0.0.0.0)
  --url    LLM server URL
  --model  Model name
  --api    API type

Other subcommands:

nixi version       Print version
nixi auth          Check web UI auth status
nixi auth --set    Set web UI password (prompts for input, empty for random)

Environment Variables#

Config File#

The user config lives at ~/.config/nixi/config.toml (or $XDG_CONFIG_HOME/nixi/config.toml). The install script creates this automatically:

[llm]
url = "http://localhost:11434"
model = "qwen3:30b-a3b"
api_type = "auto"
context_size = 32768

[paths]
data_dir = "~/.local/share/nixi/"

[containers]
container_runtime = "auto"  # "auto", "podman", or "docker"

[ui]
theme = "dark"

[web]
port = 6494
host = "0.0.0.0"
password_hash = "$2a$10$..."  # set via 'nixi auth --set'

Note: Never edit password_hash directly. Use nixi auth --set to generate valid bcrypt hashes.

API Auto-Detection#

Nixi auto-detects whether your LLM server speaks Ollama or OpenAI protocol:

• Port 11434 – assumed Ollama
• Port 1234 – assumed OpenAI (LM Studio)
• Otherwise – probes /api/tags (Ollama) and /v1/models (OpenAI)

Supported servers: Ollama, LM Studio, llama.cpp, vLLM, and any OpenAI-compatible API.

Your choice of model directly affects Nixi’s ability to use tools reliably. See Tools – LLM Models for guidance on model selection.

Context Size Defaults#

For local models, Nixi sets context size based on model size:

Remote servers control their own context size.

Node Configuration#

Remote nodes are configured with [[nodes]] sections in the config file:

[[nodes]]
name = "web-server"
host = "192.168.1.10"
user = "nixi"
mode = "managed"

[[nodes]]
name = "monitoring"
host = "192.168.1.30"
user = "nixi"
mode = "monitored"

Nodes can also be adopted interactively using the /adopt TUI command, which handles SSH key setup. See Multi-Node for the full guide.

NixOS Module Options#

The NixOS module writes a system-level config to /etc/nixi/config.toml. User config at ~/.config/nixi/config.toml overrides it, and nodes adopted via /adopt are saved to the user config.

services.nixi = {
  enable = true;
  package = inputs.nixi.packages.x86_64-linux.default;
  user = "nixi";           # default
  group = "nixi";          # default
  llmUrl = "http://localhost:11434";
  model = "qwen3:30b-a3b";
  apiType = "auto";
  contextSize = 32768;
  dataDir = "/var/lib/nixi";
  nodes = [
    { name = "web-server"; host = "192.168.1.10"; }
    { name = "monitoring"; host = "192.168.1.30"; mode = "monitored"; }
  ];

  web = {
    enable = true;       # start the web UI daemon as a systemd service
    port = 6494;         # default
    host = "0.0.0.0";   # default
  };
};

See Web UI for the full web daemon guide.