Using iocaine on NixOS, via nixocaine
Last updated: 2025-08-08

# Getting started

Lets start by declaring nixocaine as one of our flake inputs:

    {
      inputs = {
        nixpkgs.url = "github:nixos/nixpkgs/nixos-25.05";
        nixocaine = {
          url = "https://git.madhouse-project.org/iocaine/nixocaine/archive/stable.tar.gz";
          inputs.nixpkgs.follows = "nixpkgs";
        };
      };
    }

The flake exposes a NixOS module (`inputs.nixocaine.nixosModules.default`), and an overlay (`inputs.nixocaine.overlays.default`). The NixOS module automatically applies the overlay, too.

This documentation covers the `stable` branch of nixocaine.

# Attribute sets

## `services.iocaine`

The NixOS module provided by `nixocaine` declares a new service, `services.iocaine`, with the following options:

`package`

  The `iocaine` package to use. Defaults to `pkgs.iocaine-stable`, the latest stable release.

`servers.<name>.enable`

  Whether to enable the `<name>` instance. Defaults to `false`.

`servers.<name>.config`

  Configuration for the `<name>` instance of `iocaine`. The structure of it is the same as the TOML configuration, but with Nix syntax.

  Defaults to `{}`.

`servers.<name>.enableReload`

  Enables using reload instead of restart when upgrading iocaine.

  Defaults to true if `config.server.control.bind` is non-null for the instance, to false otherwise.

`servers.<name>.environment`

  Instance specific environment variables - an easier way to set them than targeting iocaine’s systemd service.

  Defaults to `{}`.

# Packages

The flake provides a single package, `iocaine-stable`, the latest iocaine release.