Skip to main content
Nix-on-Droid modules adapt the homelab configuration system for Android devices using Nix-on-Droid.

​
Overview

The Droid modules provide:
  • User profile integration with the home configuration system
  • Nix configuration optimized for mobile devices
  • Automatic home module imports for compatible configurations

​
Module Structure

modules/droid/
├── default.nix   # Module discovery and imports
├── users.nix     # User profile management
└── nixconf.nix   # Nix daemon configuration

​
User Management

The users module integrates Nix-on-Droid with the home configuration system.

​
Options

​
core.user.userName
string
default:"null"
The username for the Nix-on-Droid environment.
core.user.userName = "soriphoono";
​
core.user.shell
package
default:"pkgs.bashInteractive"
The shell to use for the user.
core.user.shell = pkgs.fish;

​
Home Manager Integration

When a username is set, the module automatically imports home configurations from:
  1. homes/<username>/default.nix - Primary user configuration
  2. homes/<username>@global/default.nix - Global settings across all platforms
  3. homes/<username>@droid/default.nix - Droid-specific overrides
The module checks for existence and only imports paths that exist.

​
Shell Integration

The Fish shell is automatically enabled in Home Manager when selected: 
core.user.shell = pkgs.fish;
# Automatically sets: core.shells.fish.enable = true

​
Example Configuration

{ pkgs, ... }: {
  core.user = {
    userName = "soriphoono";
    shell = pkgs.fish;
  };
}
This will:
  • Set the user shell to Fish
  • Import homes/soriphoono/default.nix
  • Import homes/soriphoono@global/default.nix (if exists)
  • Import homes/soriphoono@droid/default.nix (if exists)
  • Enable Fish shell in Home Manager

​
Nix Configuration

Optimized Nix daemon settings for mobile devices.

​
Installed Packages

environment.packages = [ pkgs.git ];
Git is installed by default for version control operations.

​
Nix Settings

The module configures Nix with mobile-optimized settings:

​
Experimental Features

experimental-features = nix-command flakes
Enables:
  • nix-command - New nix CLI interface
  • flakes - Flake support for reproducible configurations

​
Flake Registry

flake-registry =
Disables the global flake registry (opinionated default).

​
Resource Limits

cores = 2
Limits build jobs to 2 CPU cores to prevent out-of-memory errors during intensive compilations (e.g., browser builds).

​
Trusted Users

trusted-users = ${config.user.userName}
Grants the configured user trusted access to the Nix daemon.

​
Binary Caches

substituters = 
  https://cache.nixos.org
  https://nix-community.cachix.org
  https://numtide.cachix.org

trusted-public-keys =
  cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=
  nix-community.cachix.org-1:mB9FSh9qf2dCimDSUo8Zy7bkq5CX+/rkCWyvRCYg3Fs=
  numtide.cachix.org-1:2ps1kLBUWjxIneOy1Ik6cQjb41X0iXVXeHigGmycPPE=
Configures trusted binary caches:
  • cache.nixos.org - Official NixOS cache
  • nix-community.cachix.org - Community packages
  • numtide.cachix.org - Numtide packages

​
Flake Registry and Nix Path

The module automatically syncs the flake registry and NIX_PATH with flake inputs: 
nix.registry = lib.mapAttrs (_: flake: {inherit flake;}) flakeInputs;
nix.nixPath = lib.mapAttrsToList (n: _: "${n}=flake:${n}") flakeInputs;
This ensures nix-channel and legacy Nix commands work with flake inputs.

​
Home Module Compatibility

Nix-on-Droid can use most home modules with some adaptations:

​
Compatible Modules

  • Core Modules (with adjustments):
    • Git configuration
    • Secrets management
    • Shell configuration (Fish, Starship)
    • SSH management
  • User Applications:
    • Development tools (Neovim, editors)
    • Terminal applications
    • CLI utilities

​
Incompatible Features

  • Fastfetch - Disabled on Droid (isDroid parameter)
  • GUI Applications - Browsers, GUI editors, desktop apps
  • System Services - SystemD user services (use Termux services instead)
  • XDG MIME types - No desktop environment integration

​
Droid-Specific Adaptations

Modules can detect Droid environment: 
{ isDroid ? false, ... }: {
  programs.fastfetch = {
    enable = !isDroid;  # Disable on Droid
    # ...
  };
}
The isDroid parameter is passed to home modules automatically.

​
Complete Example

A full Nix-on-Droid configuration: 
# droid/default.nix
{ pkgs, ... }: {
  # User configuration
  core.user = {
    userName = "soriphoono";
    shell = pkgs.fish;
  };
  
  # Additional packages
  environment.packages = with pkgs; [
    git
    neovim
    tmux
  ];
}

# homes/soriphoono@droid/default.nix
{ pkgs, ... }: {
  # Droid-specific home configuration
  core = {
    git = {
      userName = "soriphoono";
      userEmail = "[email protected]";
    };
    
    shells = {
      fish.enable = true;
      
      shellAliases = {
        g = "git";
        v = "nvim";
      };
    };
  };
  
  userapps.development = {
    enable = true;
    
    editors.neovim = {
      enable = true;
      settings = import ../nvim { inherit pkgs; };
    };
  };
}

​
Directory Structure

Recommended structure for Droid configurations: 
homes/
├── soriphoono/
│   └── default.nix          # Shared desktop config
├── soriphoono@global/
│   └── default.nix          # Cross-platform config
└── soriphoono@droid/
    └── default.nix          # Droid-specific config

droid/
└── default.nix              # Droid system configuration
The @global and @droid suffixes create isolated configuration contexts:
  • @global - Applied to all platforms (desktop, servers, mobile)
  • @droid - Only applied to Nix-on-Droid installations
  • Base name - Typically used for primary desktop configuration

​
Best Practices

​
Resource Management

Mobile devices have limited resources: 
# Limit concurrent builds
nix.settings.max-jobs = 1;
nix.settings.cores = 2;

# Use binary caches aggressively
nix.settings.builders-use-substitutes = true;

​
Lightweight Configurations

Prefer CLI tools over GUI applications: 
userapps.development.editors.neovim.enable = true;  # CLI editor
# Avoid: userapps.development.editors.vscode.enable = true;  # GUI editor

​
Separate Concerns

Use the @droid suffix for mobile-specific configurations: 
# homes/user@droid/default.nix
{
  # Mobile-optimized Git settings
  core.git.projectsDir = "/storage/emulated/0/Projects";
}

​
Test Incrementally

Nix-on-Droid builds can be slow. Test modules incrementally: 
nix-on-droid switch --flake .#droid

​
Troubleshooting

​
Build Failures

Out of Memory (OOM) If builds fail with OOM errors: 
nix.settings.cores = 1;  # Reduce to 1 core
nix.settings.max-jobs = 1;
Missing Substitutes If packages aren’t available in binary caches: 
# Add more caches or build locally
nix.settings.substituters = [
  "https://cache.nixos.org"
  "https://nix-community.cachix.org"
];

​
Module Import Errors

Path Not Found Verify the home configuration paths exist: 
ls homes/username/default.nix
ls homes/username@droid/default.nix
Incompatible Options Some NixOS options don’t work on Droid. Check the module’s platform compatibility.

Build docs developers (and LLMs) love

Get started for freeTalk to us