Configuring Nix-on-Droid - Homelab: The Data Fortress

Overview

Nix-on-Droid brings the power of Nix package management to Android devices through Termux. Configurations are stored in the droids/ directory and follow the same naming patterns as Home Manager.

Nix-on-Droid runs in userspace and doesn’t require root access. It provides a Nix environment within Termux on Android.

Prerequisites

Android device with Termux installed
Nix-on-Droid app or bootstrap
Network connectivity for package downloads

Naming Patterns

Droid configurations follow the Home Manager naming convention:

Global Droid Configuration

Pattern: droids/username/default.nix Applies to all Android devices for this user.

Device-Specific Configuration

Pattern: droids/username@devicename/default.nix For device-specific settings and overrides.

Basic Configuration

Here’s a minimal Nix-on-Droid configuration:

droids/soriphoono/default.nix

{pkgs, ...}: {
  system.stateVersion = "24.05";

  core.user.shell = pkgs.fish;

  android-integration = {
    am.enable = true;
    termux-open-url.enable = true;
    termux-reload-settings.enable = true;
    termux-setup-storage.enable = true;
    xdg-open.enable = true;
  };
}

Configuration Structure

State Version

system.stateVersion

string

required

The Nix-on-Droid state version. Should match your initial installation version.Common values: "24.05", "23.11", "23.05"

Don’t change the state version after initial setup unless you know what you’re doing. It ensures compatibility with existing configurations.

User Configuration

core.user.shell

package

default:"pkgs.bash"

The default shell for the Termux environmentCommon options: pkgs.fish, pkgs.zsh, pkgs.bash

Android Integration

The android-integration namespace provides integration with Android system features:

android-integration.am.enable

boolean

default:"false"

Enable Android Activity Manager integration (start activities, send intents)

android-integration.termux-open-url.enable

boolean

default:"false"

Enable opening URLs in Android browsers from the terminal

android-integration.termux-reload-settings.enable

boolean

default:"false"

Enable reloading Termux settings

android-integration.termux-setup-storage.enable

boolean

default:"false"

Enable access to Android storage (creates symlinks to ~/storage)

android-integration.xdg-open.enable

boolean

default:"false"

Enable XDG open integration for file handling

Complete Examples

Basic Setup
Full Integration
Development Environment

Minimal configuration with Fish shell and storage access:

droids/user/default.nix

{pkgs, ...}: {
  system.stateVersion = "24.05";

  core.user.shell = pkgs.fish;

  android-integration = {
    termux-setup-storage.enable = true;
    xdg-open.enable = true;
  };
}

Complete Android integration with all features:

droids/soriphoono/default.nix

{pkgs, ...}: {
  system.stateVersion = "24.05";

  core.user.shell = pkgs.fish;

  android-integration = {
    am.enable = true;
    termux-open-url.enable = true;
    termux-reload-settings.enable = true;
    termux-setup-storage.enable = true;
    xdg-open.enable = true;
  };

  environment.packages = with pkgs; [
    git
    neovim
    ripgrep
    fd
    fzf
  ];
}

A development-focused configuration:

droids/developer/default.nix

{pkgs, ...}: {
  system.stateVersion = "24.05";

  core.user.shell = pkgs.fish;

  android-integration = {
    termux-setup-storage.enable = true;
    termux-open-url.enable = true;
    xdg-open.enable = true;
  };

  environment.packages = with pkgs; [
    # Version control
    git
    gh
    
    # Editors
    neovim
    micro
    
    # Development tools
    python3
    nodejs
    go
    
    # Search and navigation
    ripgrep
    fd
    fzf
    bat
    eza
    
    # Network tools
    curl
    wget
    openssh
  ];

  home-manager.config = {
    programs.git = {
      enable = true;
      userName = "developer";
      userEmail = "[email protected]";
    };

    programs.neovim = {
      enable = true;
      defaultEditor = true;
    };
  };
}

Installing Packages

Add packages to your Nix-on-Droid environment:

environment.packages = with pkgs; [
  git
  neovim
  tmux
  htop
  ripgrep
  fd
  fzf
];

Common Package Categories

Development Tools

environment.packages = with pkgs; [
  git
  gh              # GitHub CLI
  neovim
  python3
  nodejs
  go
  rustup
];

Shell Utilities

environment.packages = with pkgs; [
  fish
  zsh
  tmux
  starship
  zellij
  bat             # Better cat
  eza             # Better ls
  ripgrep         # Better grep
  fd              # Better find
  fzf             # Fuzzy finder
];

Network Tools

environment.packages = with pkgs; [
  curl
  wget
  openssh
  rsync
  nmap
  inetutils
];

System Utilities

environment.packages = with pkgs; [
  htop
  btop
  procps
  file
  tree
  zip
  unzip
];

Home Manager Integration

Nix-on-Droid can use Home Manager for user-level configuration:

droids/user/default.nix

{pkgs, ...}: {
  system.stateVersion = "24.05";
  
  home-manager.config = {
    programs.git = {
      enable = true;
      userName = "user";
      userEmail = "[email protected]";
    };
    
    programs.fish = {
      enable = true;
      shellInit = ''
        set -g fish_greeting
      '';
    };
  };
}

Linking to Home Manager Configs

You can reference existing Home Manager configurations:

droids/soriphoono/default.nix

{pkgs, ...}: {
  system.stateVersion = "24.05";
  
  # Reference the home manager config for this user
  home-manager.config = import ../../homes/soriphoono@droid/default.nix;
}

Then create homes/soriphoono@droid/default.nix:

homes/soriphoono@droid/default.nix

{pkgs, ...}: {
  core.git = {
    userName = "soriphoono";
    userEmail = "[email protected]";
  };
  
  userapps.development.editors.neovim.enable = true;
}

Storage Access

When termux-setup-storage.enable = true, Termux creates symlinks in your home directory:

~/storage/
├── dcim/           -> /storage/emulated/0/DCIM
├── downloads/      -> /storage/emulated/0/Download
├── movies/         -> /storage/emulated/0/Movies
├── music/          -> /storage/emulated/0/Music
├── pictures/       -> /storage/emulated/0/Pictures
├── shared/         -> /storage/emulated/0
└── external-1/     -> /storage/XXXX-XXXX (SD card)

Use ~/storage/shared to access your Android’s internal storage root.

Using Droid Modules

Custom modules for Nix-on-Droid are located in modules/droid/:

modules/droid/
├── default.nix      # Module discovery
├── users.nix        # User configuration
└── nixconf.nix      # Nix configuration

Modules are automatically imported and available in your configuration:

core.user.shell = pkgs.fish;  # From modules/droid/users.nix

Building and Deploying

Local Build

From your homelab repository:

nix-on-droid build --flake .#droid-soriphoono

Deploy to Device

nix-on-droid switch --flake .#droid-soriphoono

Remote Build

Build on a more powerful machine and deploy:

# On your workstation
nix build .#nixOnDroidConfigurations.droid-soriphoono.activationPackage

# Copy to device
scp result/activate phone:/data/data/com.termux.nix/files/home/

# On device
~/activate

Available Modules

The following core modules are available for Nix-on-Droid:

Core Modules

core.user - User environment configuration
core.nixconf - Nix daemon and settings

Android Integration

android-integration.am - Activity Manager
android-integration.termux-* - Termux utilities
android-integration.xdg-open - File handling

Troubleshooting

Permission Issues

If you encounter permission errors:

# Request storage permissions
termux-setup-storage

# Check Termux permissions in Android settings
# Settings > Apps > Termux > Permissions

Build Failures

Clear the build cache:

nix-store --gc
nix-on-droid switch --flake .#droid-user

Package Not Found

Some packages may not be available for Android/ARM:

environment.packages = with pkgs; [
  # Check if package supports your architecture
] ++ lib.optionals pkgs.stdenv.isLinux [
  # Linux-only packages
];

Limitations

Nix-on-Droid has some limitations compared to full NixOS:

No root access (runs in Termux userspace)
Limited system integration
Some packages may not be available for ARM/Android
No systemd or system services
Storage access requires permissions

Best Practices

Start minimal - Begin with a basic configuration and add packages as needed
Use Home Manager - Leverage Home Manager for consistent configs across devices
Enable storage access - Set up storage integration early
Test locally - Build configurations locally before deploying to device
Version control - Keep your droid configs in Git like other configurations

Next Steps

Home Manager

Share configs between desktop and Android

Modules

Learn about available modules

Development

Set up your development environment

Deployment

Deploy configurations to devices

Get Started

Core Concepts

Deployment

Configuration

Operations

Guides

​Overview

​Prerequisites

​Naming Patterns

​Global Droid Configuration

​Device-Specific Configuration

​Basic Configuration

​Configuration Structure

​State Version

​User Configuration

​Android Integration

​Complete Examples

​Installing Packages

​Common Package Categories

​Home Manager Integration

​Linking to Home Manager Configs

​Storage Access

​Using Droid Modules

​Building and Deploying

​Local Build

​Deploy to Device

​Remote Build

​Available Modules

​Core Modules

​Android Integration

​Troubleshooting

​Permission Issues

​Build Failures

​Package Not Found

​Limitations

​Best Practices

​Next Steps

Home Manager

Modules

Development

Deployment

Build docs developers (and LLMs) love

Overview

Prerequisites

Naming Patterns

Global Droid Configuration

Device-Specific Configuration

Basic Configuration

Configuration Structure

State Version

User Configuration

Android Integration

Complete Examples

Installing Packages

Common Package Categories

Home Manager Integration

Linking to Home Manager Configs

Storage Access

Using Droid Modules

Building and Deploying

Local Build

Deploy to Device

Remote Build

Available Modules

Core Modules

Android Integration

Troubleshooting

Permission Issues

Build Failures

Package Not Found

Limitations

Best Practices

Next Steps