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

# Configuring Nix-on-Droid

> Learn how to configure Android devices with Nix-on-Droid

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

<Note>
  Nix-on-Droid runs in userspace and doesn't require root access. It provides a Nix environment within Termux on Android.
</Note>

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

```nix droids/soriphoono/default.nix theme={null}
{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

<ParamField path="system.stateVersion" type="string" required>
  The Nix-on-Droid state version. Should match your initial installation version.

  Common values: `"24.05"`, `"23.11"`, `"23.05"`
</ParamField>

<Warning>
  Don't change the state version after initial setup unless you know what you're doing. It ensures compatibility with existing configurations.
</Warning>

### User Configuration

<ParamField path="core.user.shell" type="package" default="pkgs.bash">
  The default shell for the Termux environment

  Common options: `pkgs.fish`, `pkgs.zsh`, `pkgs.bash`
</ParamField>

### Android Integration

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

<ParamField path="android-integration.am.enable" type="boolean" default="false">
  Enable Android Activity Manager integration (start activities, send intents)
</ParamField>

<ParamField path="android-integration.termux-open-url.enable" type="boolean" default="false">
  Enable opening URLs in Android browsers from the terminal
</ParamField>

<ParamField path="android-integration.termux-reload-settings.enable" type="boolean" default="false">
  Enable reloading Termux settings
</ParamField>

<ParamField path="android-integration.termux-setup-storage.enable" type="boolean" default="false">
  Enable access to Android storage (creates symlinks to \~/storage)
</ParamField>

<ParamField path="android-integration.xdg-open.enable" type="boolean" default="false">
  Enable XDG open integration for file handling
</ParamField>

## Complete Examples

<Tabs>
  <Tab title="Basic Setup">
    Minimal configuration with Fish shell and storage access:

    ```nix droids/user/default.nix theme={null}
    {pkgs, ...}: {
      system.stateVersion = "24.05";

      core.user.shell = pkgs.fish;

      android-integration = {
        termux-setup-storage.enable = true;
        xdg-open.enable = true;
      };
    }
    ```
  </Tab>

  <Tab title="Full Integration">
    Complete Android integration with all features:

    ```nix droids/soriphoono/default.nix theme={null}
    {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
      ];
    }
    ```
  </Tab>

  <Tab title="Development Environment">
    A development-focused configuration:

    ```nix droids/developer/default.nix theme={null}
    {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 = "dev@example.com";
        };

        programs.neovim = {
          enable = true;
          defaultEditor = true;
        };
      };
    }
    ```
  </Tab>
</Tabs>

## Installing Packages

Add packages to your Nix-on-Droid environment:

```nix theme={null}
environment.packages = with pkgs; [
  git
  neovim
  tmux
  htop
  ripgrep
  fd
  fzf
];
```

### Common Package Categories

<AccordionGroup>
  <Accordion title="Development Tools">
    ```nix theme={null}
    environment.packages = with pkgs; [
      git
      gh              # GitHub CLI
      neovim
      python3
      nodejs
      go
      rustup
    ];
    ```
  </Accordion>

  <Accordion title="Shell Utilities">
    ```nix theme={null}
    environment.packages = with pkgs; [
      fish
      zsh
      tmux
      starship
      zellij
      bat             # Better cat
      eza             # Better ls
      ripgrep         # Better grep
      fd              # Better find
      fzf             # Fuzzy finder
    ];
    ```
  </Accordion>

  <Accordion title="Network Tools">
    ```nix theme={null}
    environment.packages = with pkgs; [
      curl
      wget
      openssh
      rsync
      nmap
      inetutils
    ];
    ```
  </Accordion>

  <Accordion title="System Utilities">
    ```nix theme={null}
    environment.packages = with pkgs; [
      htop
      btop
      procps
      file
      tree
      zip
      unzip
    ];
    ```
  </Accordion>
</AccordionGroup>

## Home Manager Integration

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

```nix droids/user/default.nix theme={null}
{pkgs, ...}: {
  system.stateVersion = "24.05";
  
  home-manager.config = {
    programs.git = {
      enable = true;
      userName = "user";
      userEmail = "user@example.com";
    };
    
    programs.fish = {
      enable = true;
      shellInit = ''
        set -g fish_greeting
      '';
    };
  };
}
```

### Linking to Home Manager Configs

You can reference existing Home Manager configurations:

```nix droids/soriphoono/default.nix theme={null}
{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`:

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

<Tip>
  Use `~/storage/shared` to access your Android's internal storage root.
</Tip>

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

```nix theme={null}
core.user.shell = pkgs.fish;  # From modules/droid/users.nix
```

## Building and Deploying

### Local Build

From your homelab repository:

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

### Deploy to Device

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

### Remote Build

Build on a more powerful machine and deploy:

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

```bash theme={null}
# Request storage permissions
termux-setup-storage

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

### Build Failures

Clear the build cache:

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

### Package Not Found

Some packages may not be available for Android/ARM:

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

## Limitations

<Warning>
  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
</Warning>

## Best Practices

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

## Next Steps

<CardGroup cols={2}>
  <Card title="Home Manager" icon="house" href="/configuration/homes">
    Share configs between desktop and Android
  </Card>

  <Card title="Modules" icon="puzzle-piece" href="/configuration/modules">
    Learn about available modules
  </Card>

  <Card title="Development" icon="code" href="/operations/development-environment">
    Set up your development environment
  </Card>

  <Card title="Deployment" icon="rocket" href="/deployment/nix-on-droid">
    Deploy configurations to devices
  </Card>
</CardGroup>