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,
    ...
  }: {
    nixosConfigurations."..." = nixpkgs.lib.nixosSystem {
      system = "<system>"; # e.g., x86_64-linux
      modules = [
        # ... your other configuration modules ...
        vicinae.nixosModules.default
      ];
    };

    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.

nix.conf or flake.nix

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

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

home.nix

{ 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;
        family = "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:

home.nix

{
#...
  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

Declaratively Managing Secrets with sops-nix

This example assumes that you are familiar with secret management and template management through sops-nix.

In your sops secrets file, add the secrets you want to use in Vicinae.

secrets.sops.yaml

github: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

We're going to use sops-nix's template feature in this example. Templates allow you to generate configuration files dynamically, in Nix, while still keeping the actual secret values encrypted and out of your Nix store. You can define individual secrets in your sops file and compose them into structured files using placeholders like config.sops.placeholder.<secret-name>. At activation time, sops-nix renders the template with the decrypted secret values and writes the final file securely to disk. As an additional benefit to this approach, you can still use the secrets elsewhere without needing to declare them multiple times in your sops secrets file.

In either your home.nix or your configuration.nix add your sops-nix configuration:

home.nix or configuration.nix

{ config, ... }:
{
#...
  sops = {
    secrets = {
      github = { };
      # ... - you can add more secrets if needed
    };
    templates = {
      "vicinae-secrets.json" = {  # wrapped in "quotes" because it contains a dot
        owner = "your-username";  # if you are using `home-manager`, you can omit this
        content = builtins.toJSON {
          providers = {
            "@knoopx/nix" = {  # wrapped in "quotes" because it contains a `@` and a slash
              preferences = {
                githubToken = config.sops.placeholder.github; 
              };
            };
          };
        };
      };
    };
  };
}

Finally, add the sops-nix template file to Vicinae's settings as an import:

home.nix

{
  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.templates."vicinae-secrets.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.