> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/soriphoono/homelab/llms.txt
> Use this file to discover all available pages before exploring further.

# Nix-on-Droid Modules

> Module reference for Nix-on-Droid mobile configurations

Nix-on-Droid modules adapt the homelab configuration system for Android devices using [Nix-on-Droid](https://github.com/nix-community/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

<ParamField path="core.user.userName" type="string" default="null">
  The username for the Nix-on-Droid environment.

  ```nix theme={null}
  core.user.userName = "soriphoono";
  ```
</ParamField>

<ParamField path="core.user.shell" type="package" default="pkgs.bashInteractive">
  The shell to use for the user.

  ```nix theme={null}
  core.user.shell = pkgs.fish;
  ```
</ParamField>

### 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:

```nix theme={null}
core.user.shell = pkgs.fish;
# Automatically sets: core.shells.fish.enable = true
```

### Example Configuration

```nix theme={null}
{ 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

```nix theme={null}
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

```nix theme={null}
experimental-features = nix-command flakes
```

Enables:

* **nix-command** - New `nix` CLI interface
* **flakes** - Flake support for reproducible configurations

#### Flake Registry

```nix theme={null}
flake-registry =
```

Disables the global flake registry (opinionated default).

#### Resource Limits

```nix theme={null}
cores = 2
```

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

#### Trusted Users

```nix theme={null}
trusted-users = ${config.user.userName}
```

Grants the configured user trusted access to the Nix daemon.

#### Binary Caches

```nix theme={null}
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 theme={null}
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:

```nix theme={null}
{ 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:

```nix theme={null}
# droid/default.nix
{ pkgs, ... }: {
  # User configuration
  core.user = {
    userName = "soriphoono";
    shell = pkgs.fish;
  };
  
  # Additional packages
  environment.packages = with pkgs; [
    git
    neovim
    tmux
  ];
}
```

```nix theme={null}
# homes/soriphoono@droid/default.nix
{ pkgs, ... }: {
  # Droid-specific home configuration
  core = {
    git = {
      userName = "soriphoono";
      userEmail = "soriphoono@gmail.com";
    };
    
    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:

```nix theme={null}
# 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:

```nix theme={null}
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:

```nix theme={null}
# 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:

```bash theme={null}
nix-on-droid switch --flake .#droid
```

***

## Troubleshooting

### Build Failures

**Out of Memory (OOM)**

If builds fail with OOM errors:

```nix theme={null}
nix.settings.cores = 1;  # Reduce to 1 core
nix.settings.max-jobs = 1;
```

**Missing Substitutes**

If packages aren't available in binary caches:

```nix theme={null}
# 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:

```bash theme={null}
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.

***

## Related Resources

* [Nix-on-Droid GitHub](https://github.com/nix-community/nix-on-droid)
* [Nix-on-Droid Wiki](https://github.com/nix-community/nix-on-droid/wiki)
* [Home Manager Manual](https://nix-community.github.io/home-manager/)