Nix Modules

NixOS Module

Vira provides a NixOS module for easy deployment. See the NixOS configuration example for usage.

Home Manager Module

Vira provides a Home Manager module for running Vira as a user service. Supports Linux (systemd user services) and macOS (launchd agents).

macOS Limitations

Warning

The home-manager service has several limitations on macOS due to launchd requirements:

Headless Mac Issue

On headless macOS systems (servers without GUI), the service will fail to start with the error: 

Failed to start agent 'gui/502/org.vira.service' with error: Bootstrap failed: 125: Domain does not support specified action

Workaround: Log into the GUI session first, then lock the user immediately. The service requires an active GUI session context to bootstrap properly, even if running in the background.

Service Restart

The home-manager service may stop for any reason on macOS. You can bring it back by running: 

launchctl load ~/Library/LaunchAgents/org.vira.service.plist

Configuration

See the Home Manager configuration example for usage.

Available Options

Both NixOS and Home Manager modules support the following configuration options:

  • enable - Enable the Vira service (default: false)
  • package - The Vira package to use
  • hostname - Hostname to bind Vira to (default: "localhost")
  • port - Port to bind Vira to (default: 5005)
  • https - Enable HTTPS (default: true)
  • stateDir - Directory to store Vira state data
  • basePath - Base URL path for the HTTP server (default: "/")
  • autoResetState - Automatically reset state on schema mismatch, removing ViraState and job workspaces (default: true)
  • extraPackages - Extra packages to add to the Vira service PATH
  • initialState.repositories - Map of repository names to clone URLs for initial state
Note

The autoResetState option is enabled by default to ensure smooth upgrades when Vira’s internal state schema changes. If you prefer to preserve state across schema changes (and handle migrations manually), set this to false.