Nixos

Vicinae is available as a Nix flake but can also be run without installing. You can use the binaries of the Nix package or enable the systemd service provided by the home-manager module.

Run Vicinae without installing

You can test the app directly by using a nix shell

nix shell github:vicinaehq/vicinae

Home Manager module

If you don’t want to compile Vicinae yourself, make sure to enable Cachix

# flake.nix
{
  inputs = {
    # ...
    vicinae.url = "github:vicinaehq/vicinae";
  };
  outputs =
    {
      nixpkgs,
      home-manager,
      vicinae,
      ...
    }:
    {
      homeConfigurations."..." = home-manager.lib.homeManagerConfiguration {
        pkgs = nixpkgs.legacyPackages."<system>"; # e.g. x86_64-linux
        modules = [ vicinae.homeManagerModules.default ];
      };
    };
}

# home.nix
{
  # ...

  services.vicinae = {
    enable = true; # default: false
    systemd = {
      enable = true; # default: false
      autoStart = true; # default: false
      environment = {
        USE_LAYER_SHELL = 1;
      };
    };
  };
}

Cachix

If you want to use the cache do not add inputs.nixpkgs.follows = "nixpkgs"; to your flake! This will make the cache miss.

The Vicinae flake is not built by Hydra, so it is not cached in cache.nixos.org, like the rest of Nixpkgs. Instead of requiring you to build Vicinae every time it updates, we provide a Cachix cache that you can add to your Nix configuration.

extra-substituters = [ "https://vicinae.cachix.org" ];
extra-trusted-public-keys = [ "vicinae.cachix.org-1:1kDrfienkGHPYbkpNj1mWTr7Fm1+zcenzgTizIcI3oc=" ];

Alterntively you can use the vicinae package from nixpkgs which is build by Hydra, but may be out of date:

{ pkgs, ... }:
{
  services.vicinae = {
    package = pkgs.vicinae;
  };
}

Configuring with Home Manager

You can configure Vicinae using Home Manager options. Here is an example configuration: flake.nix:

 inputs.vicinae-extensions = {
   url = "github:vicinaehq/extensions";
   inputs.nixpkgs.follows = "nixpkgs";
 };

home.nix:

services.vicinae = {
  enable = true;
  systemd = {
    enable = true;
    autoStart = true; # default: false
    environment = {
      USE_LAYER_SHELL = 1;
    };
  };
  settings = {
    close_on_focus_loss = true;
    consider_preedit = true;
    pop_to_root_on_close = true;
    favicon_service = "twenty";
    search_files_in_root = true;
    font = {
      normal = {
        size = 12;
        normal = "Maple Nerd Font";
      };
    };
    theme = {
      light = {
        name = "vicinae-light";
        icon_theme = "default";
      };
      dark = {
        name = "vicinae-dark";
        icon_theme = "default";
      };
    };
    launcher_window = {
      opacity = 0.98;
    };
  };
  extensions = with inputs.vicinae-extensions.packages.${pkgs.stdenv.hostPlatform.system}; [
     bluetooth
     nix
     power-profile
    # Extension names can be found in the link below, it's just the folder names
  ];
};

Extension names

Configuring Extensions

To configure extensions with options declaratively, add their configuration as such:

{
#...
  services.vicinae.settings = {
    providers = {
       # Notice name difference. If declaring install and not installing manually, the name is different
      "@knoopx/nix-0" = {
        preferences = {
          # Declaring Secrets to a public repo is not good. See section below for secrets management
          githubToken = "TOKEN HERE";
        };
      };
    };
  };
}

This will vary depending on the fields that each extension expects. This is not limited to Vicinae extensions, but also works for any other "entrypoint." So Raycast should also be configurable. View the "package.json" for your desired extension to see the options

For Sops Users Wishing to declare configs with secrets

This example assumes working knowledge of Sops Nix - Sops-Nix Repo

In your sops secrets file add something similar to this:

vicinae.json: |
    {
        "providers": {
          "@knoopx/nix-0": {
             "preferences": {
                "githubToken": "TOKEN HERE"
             }
          }
        }
    }

In either your home.nix or your configuration.nix add your sops declaration

{
#...
  sops = {
    secrets = {
      "vicinae.json" = {
        owner = username;
      };
    #...
    };
  };
}

Finally, add your sops secrets as an import

{
  services.vicinae.settings = {
    # NOTE: If you have sops configured in your home.nix, it will be config.sops... otherwise, depending on how your nix is configured, it may be nixosConfig.sops...
    imports = [nixosConfig.sops.secrets."vicinae.json".path];
  };
}

the theme.name option can be set to any of the themes that come with Vicinae or a custom theme you have installed. See the Github for more information on default theme names.