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

# Deploying to Android Devices

> Deploy Nix configurations to Android devices using Nix-on-Droid

Manage Android devices declaratively using Nix-on-Droid, bringing the power of NixOS-style configuration to mobile devices.

## Overview

Nix-on-Droid configurations are stored in the `droids/` directory. Each directory is automatically discovered and exposed as a `nixOnDroidConfiguration`.

## Prerequisites

### Android Device Requirements

* Android device with ARM64 architecture (most modern devices)
* Termux installed from F-Droid (NOT Google Play Store)
* Storage permissions granted to Termux
* Stable internet connection
* At least 2GB free storage

<Warning>
  Install Termux from F-Droid, not Google Play Store. The Play Store version is outdated and incompatible with Nix-on-Droid.
</Warning>

### Initial Device Setup

Before deploying configurations, set up Nix-on-Droid on your device:

<Steps>
  <Step title="Install Termux">
    Download and install Termux from [F-Droid](https://f-droid.org/packages/com.termux/).
  </Step>

  <Step title="Grant storage permissions">
    In Termux, run:

    ```bash theme={null}
    termux-setup-storage
    ```

    Grant permission when prompted.
  </Step>

  <Step title="Install Nix-on-Droid">
    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/nix-community/nix-on-droid/master/install.sh | bash
    ```

    This installs Nix and sets up the Nix-on-Droid environment.
  </Step>

  <Step title="Restart Termux">
    Close and reopen Termux to load the new environment.
  </Step>
</Steps>

## Flake Configuration

The flake uses automatic discovery for Nix-on-Droid configurations:

```nix theme={null}
nixOnDroidConfigurations = lib.mapAttrs mkDroid (lib.discover ./droids);
```

Each directory in `droids/` is automatically available for deployment.

### Architecture Settings

Nix-on-Droid configurations are built for `aarch64-linux` using the `nixpkgs-droid` input:

```nix theme={null}
mkDroid = name: path: let
  systemArch = "aarch64-linux";
  pkgs = import nixpkgs-droid {
    system = systemArch;
    config.allowUnfree = true;
  };
in
  nix-on-droid.lib.nixOnDroidConfiguration {
    inherit pkgs;
    modules = droidModules ++ [path];
  };
```

## Deployment from Android Device

Deploy directly on the Android device itself.

<Steps>
  <Step title="Clone repository on device">
    In Termux:

    ```bash theme={null}
    cd ~
    git clone <your-repo-url> homelab
    cd homelab
    ```
  </Step>

  <Step title="Validate configuration">
    ```bash theme={null}
    nix flake check
    ```
  </Step>

  <Step title="Deploy configuration">
    ```bash theme={null}
    nix-on-droid switch --flake .#<device-name>
    ```

    Replace `<device-name>` with your configuration name from `droids/`.
  </Step>
</Steps>

## Deployment from Desktop

Build configurations on a desktop machine and deploy to the device.

<Steps>
  <Step title="Build on desktop">
    On your desktop/laptop:

    ```bash theme={null}
    cd /path/to/homelab
    nix build .#nixOnDroidConfigurations.<device-name>.activationPackage
    ```
  </Step>

  <Step title="Copy to device">
    Transfer the built configuration:

    ```bash theme={null}
    # Find the result path
    readlink -f result

    # Copy via various methods:
    # Method 1: Using adb
    adb push result /data/data/com.termux/files/home/config

    # Method 2: Using SSH (if configured)
    scp -r result user@android-device:~/config

    # Method 3: Via cloud storage or file sharing
    # Upload result and download on device
    ```
  </Step>

  <Step title="Activate on device">
    In Termux on the Android device:

    ```bash theme={null}
    ~/config/activate
    ```
  </Step>
</Steps>

## Configuration Structure

Each Nix-on-Droid configuration should be structured as:

```
droids/<device-name>/
├── default.nix      # Main configuration
├── home.nix         # Home Manager settings (optional)
└── packages.nix     # Device-specific packages (optional)
```

## Home Manager Integration

Nix-on-Droid includes integrated Home Manager support:

```nix theme={null}
droidModules = [
  self.droidModules.default
  {
    home-manager = {
      useGlobalPkgs = true;
      extraSpecialArgs = { inherit inputs self lib; isDroid = true; };
      sharedModules = homeManagerModules;
      backupFileExtension = "bak";
    };
  }
];
```

Your device configuration can include Home Manager modules:

```nix theme={null}
# droids/phone/default.nix
{ pkgs, ... }:
{
  # Nix-on-Droid settings
  time.timeZone = "America/New_York";
  
  # Home Manager settings
  home-manager.config = { ... };
}
```

## Common Configuration Examples

### Basic Configuration

```nix theme={null}
# droids/phone/default.nix
{ pkgs, ... }:
{
  # Set timezone
  time.timeZone = "America/New_York";
  
  # Install packages
  environment.packages = with pkgs; [
    vim
    git
    htop
    tmux
  ];
  
  # User configuration
  user.shell = "${pkgs.zsh}/bin/zsh";
}
```

### With Home Manager

```nix theme={null}
# droids/phone/default.nix
{ pkgs, ... }:
{
  time.timeZone = "America/New_York";
  
  environment.packages = with pkgs; [ vim git ];
  
  home-manager.config = {
    programs.zsh = {
      enable = true;
      enableCompletion = true;
      syntaxHighlighting.enable = true;
    };
    
    programs.git = {
      enable = true;
      userName = "Your Name";
      userEmail = "your.email@example.com";
    };
  };
}
```

## Flake Reference Format

Nix-on-Droid uses this flake reference:

```
.#<device-name>
```

Where:

* `.` refers to the current directory (flake root)
* `#` separates the flake reference from the output
* `<device-name>` matches directory name in `droids/`

## Rollback and Recovery

### List Generations

```bash theme={null}
nix-on-droid list-generations
```

### Rollback to Previous Generation

```bash theme={null}
nix-on-droid rollback
```

### Switch to Specific Generation

```bash theme={null}
nix-on-droid switch --rollback --generation <number>
```

## Troubleshooting

### Installation Issues

**Problem**: Nix installation fails on Android

**Solutions**:

1. Ensure Termux is from F-Droid
2. Grant storage permissions
3. Check internet connectivity
4. Ensure sufficient storage space
5. Try clearing Termux cache

### Build Failures

**Problem**: Configuration fails to build

**Solutions**:

1. Run `nix flake check` first
2. Verify architecture is `aarch64-linux`
3. Check that all packages support ARM64
4. Review error messages for unsupported packages
5. Test build on desktop: `nix build .#nixOnDroidConfigurations.<device-name>.activationPackage`

### Storage Issues

**Problem**: Running out of storage

**Solutions**:

```bash theme={null}
# Clean old generations
nix-collect-garbage -d

# Check Nix store size
du -sh ~/.nix-profile

# Remove specific generations
nix-on-droid remove-generations 7d
```

### Package Not Available

**Problem**: Package doesn't work on Android

**Solutions**:

* Some packages don't support ARM64 or Android
* Check if package is in `aarch64-linux` cache
* Consider alternatives or building from source
* Review package meta.platforms

## Performance Considerations

<Warning>
  Initial builds on Android devices can be slow and battery-intensive. Consider building on a desktop and transferring the result.
</Warning>

### Optimization Tips

1. **Use Binary Caches**: Configure substituters to avoid building on device
   ```nix theme={null}
   nix.extraOptions = ''
     substituters = https://cache.nixos.org https://nix-community.cachix.org
   '';
   ```

2. **Minimize Packages**: Only install essential packages on device

3. **Build Remotely**: Build on desktop when possible

4. **Cleanup Regularly**: Remove old generations to save space

## Remote Access

Configure SSH for remote access to your Android device:

```nix theme={null}
# droids/phone/default.nix
{ pkgs, ... }:
{
  environment.packages = [ pkgs.openssh ];
  
  # SSH daemon will be available in Termux
  # Start with: sshd
}
```

## Best Practices

* Test configurations on desktop first
* Keep device configs minimal
* Use binary caches to avoid local builds
* Regularly clean old generations
* Backup important data before major changes
* Monitor storage usage
* Keep Termux and Nix updated

<Warning>
  Always run `nix flake check` before deploying to ensure configuration is valid. Failed deployments on Android can be harder to recover from.
</Warning>

## Next Steps

* [Validation](/deployment/validation) - Pre-deployment validation
* [NixOS Systems](/deployment/nixos-systems) - Deploy full systems
* [Home Manager](/deployment/home-manager) - User configurations