### Load Container Configuration from File

Source: https://context7.com/ravindu644/droidspaces-oss/llms.txt

Starts a container using a specified configuration file. This allows for reproducible container setups by defining all parameters in a single file.

```bash
sudo droidspaces --conf=/path/to/mycontainer.config start
```

--------------------------------

### Execute Common Droidspaces Workflows

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Linux-CLI.md

Examples for starting persistent or ephemeral containers and executing one-off commands.

```bash
sudo droidspaces \
  --name=dev \
  --rootfs=/path/to/ubuntu-rootfs \
  --hostname=devbox \
  --bind-mount=/home/user/projects:/workspace \
  start
```

```bash
sudo droidspaces \
  --name=server \
  --rootfs-img=/path/to/rootfs.img \
  --net=nat \
  --upstream=wlan0,rmnet0 \
  --port=8080:80 \
  start
```

```bash
sudo droidspaces --name=test --rootfs=/path/to/rootfs --volatile start
```

```bash
sudo droidspaces --name=mycontainer run uname -a
# Use sh -c for pipes:
sudo droidspaces --name=mycontainer run sh -c "ps aux | grep init"
```

--------------------------------

### Install Docker

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Cool-things-you-can-do.md

Command to install Docker using the official convenience script.

```bash
# Using the official convenience script
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh
```

--------------------------------

### Enable and Start systemd Watchdog Service

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Troubleshooting.md

Reload systemd to recognize the new service, enable it to start on boot, and then start it immediately.

```shell
# Reload systemd to pick up the new service
systemctl daemon-reload

# Enable it to start on boot
systemctl enable wifi-watchdog

# Start it now
systemctl start wifi-watchdog
```

--------------------------------

### Launch XFCE Desktop Environment

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/GPU-Acceleration.md

Execute this command within the container to start the XFCE desktop environment if it is installed.

```bash
dbus-launch --exit-with-session startxfce4
```

--------------------------------

### Start VirGL Server

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/GPU-Acceleration.md

Initializes the VirGL test server in the background on the host.

```bash
virgl_test_server_android &
```

--------------------------------

### Enable and Start OpenRC Watchdog Service

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Troubleshooting.md

Make the OpenRC service file executable and add it to the default runlevel, then start the service.

```shell
chmod +x /etc/init.d/wifi-watchdog
rc-update add wifi-watchdog default
rc-service wifi-watchdog start
```

--------------------------------

### Start VirGL Server with Vulkan Backend

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/GPU-Acceleration.md

Alternative command to start the VirGL server using the Vulkan backend if the default renderer fails.

```bash
virgl_test_server_android --angle-vulkan &
```

--------------------------------

### Start Droidspaces Container in Foreground

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Linux-CLI.md

Attach to the container's console upon starting to view init logs directly.

```bash
--foreground
```

--------------------------------

### Start a Container

Source: https://context7.com/ravindu644/droidspaces-oss/llms.txt

Boots a container from a rootfs directory or ext4 image. Supports custom hostnames, DNS, and foreground logging.

```bash
# Start container from a rootfs directory
sudo droidspaces --rootfs=/path/to/ubuntu-rootfs --name=ubuntu start

# Start container from an ext4 image file (recommended for Android)
sudo droidspaces --rootfs-img=/path/to/rootfs.img --name=mycontainer start

# Start with custom hostname and DNS
sudo droidspaces --rootfs=/path/to/rootfs --name=devbox --hostname=dev-server --dns=1.1.1.1,8.8.8.8 start

# Start in foreground mode to see init logs
sudo droidspaces --rootfs=/path/to/rootfs --name=test --foreground start
```

--------------------------------

### Start a Droidspaces Container

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Linux-CLI.md

Use this command to start a new container. Specify the root filesystem path either as a directory or an ext4 image file.

```bash
sudo droidspaces --rootfs=/path/to/rootfs start
```

```bash
sudo droidspaces --name=mycontainer --rootfs-img=/path/to/rootfs.img start
```

--------------------------------

### Start Container in Foreground Mode

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Troubleshooting.md

Start a container in foreground mode to get more detailed output for debugging. Requires specifying the rootfs path.

```shell
droidspaces --name=mycontainer --rootfs=/path/to/rootfs --foreground start
```

--------------------------------

### Test Package Installations in Volatile Container

Source: https://context7.com/ravindu644/droidspaces-oss/llms.txt

Demonstrates installing packages within a volatile container. Changes made, such as package installations, will be lost when the container is stopped, making it suitable for testing.

```bash
sudo droidspaces --name=sandbox enter
# Inside container:
apt update && apt install -y nginx  # Changes lost on container stop
```

--------------------------------

### Install and Authenticate Tailscale

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Cool-things-you-can-do.md

Commands to install the Tailscale P2P tunnel and authenticate the container.

```bash
curl -fsSL https://tailscale.com/install.sh | sh
```

```bash
tailscale up
```

--------------------------------

### Bind Mount Syntax Examples

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Features.md

Demonstrates the syntax for single and multiple bind mounts using the --bind-mount and -B flags. Supports comma-separated or chained multiple mounts.

```bash
# Single mount
--bind-mount=/host/path:/container/path
-B /host/path:/container/path
```

```bash
# Multiple mounts (comma-separated)
-B /src1:/dst1,/src2:/dst2,/src3:/dst3
```

```bash
# Multiple mounts (chained)
-B /src1:/dst1 -B /src2:/dst2
```

```bash
# Mix and match
-B /src1:/dst1,/src2:/dst2 -B /src3:/dst3
```

--------------------------------

### Start a Container

Source: https://context7.com/ravindu644/droidspaces-oss/llms.txt

Boots a new container from either a rootfs directory or an ext4 image file. The container runs a real init system (systemd, OpenRC, etc.) as PID 1 with full service management capabilities.

```APIDOC
## START CONTAINER

### Description
Boots a new container from either a rootfs directory or an ext4 image file. The container runs a real init system (systemd, OpenRC, etc.) as PID 1 with full service management capabilities.

### Method
`droidspaces start`

### Parameters
#### Path Parameters
None

#### Query Parameters
- `--rootfs` (string) - Required - Path to the rootfs directory.
- `--rootfs-img` (string) - Required - Path to the ext4 image file (recommended for Android).
- `--name` (string) - Optional - Name for the container.
- `--hostname` (string) - Optional - Custom hostname for the container.
- `--dns` (string) - Optional - Comma-separated list of DNS servers.
- `--foreground` (boolean) - Optional - Start in foreground mode to see init logs.

### Request Example
```bash
sudo droidspaces --rootfs=/path/to/ubuntu-rootfs --name=ubuntu start
sudo droidspaces --rootfs-img=/path/to/rootfs.img --name=mycontainer start
sudo droidspaces --rootfs=/path/to/rootfs --name=devbox --hostname=dev-server --dns=1.1.1.1,8.8.8.8 start
sudo droidspaces --rootfs=/path/to/rootfs --name=test --foreground start
```
```

--------------------------------

### Install Networking Tools and Set iptables Legacy

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Cool-things-you-can-do.md

Installs essential networking tools like net-tools and iptables, then configures the system to use the legacy iptables backend, which is often required for Droidspaces on Android kernels.

```bash
apt update && apt install -y net-tools iptables
```

```bash
update-alternatives --set iptables /usr/sbin/iptables-legacy
update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy
```

--------------------------------

### Start Volatile Containers

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Features.md

Commands to launch a volatile container using either a directory or a rootfs image as the base.

```bash
# Volatile container from a directory
droidspaces --name=test --rootfs=/path/to/rootfs --volatile start

# Volatile container from an image
droidspaces --name=test --rootfs-img=/path/to/rootfs.img --volatile start
```

--------------------------------

### Install and Configure Fail2Ban

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Cool-things-you-can-do.md

Commands to install Fail2Ban, define the local jail configuration, and verify the service status.

```bash
apt install -y fail2ban
```

```ini
[DEFAULT]
# Ban for 1 hour after 5 failed attempts within 10 minutes
bantime  = 1h
findtime = 10m
maxretry = 5

# Use UFW as the banning action
banaction = ufw

# Whitelist to prevent accidental lockouts:
# 1. YOUR_TAILSCALE_IP: Your private tunnel address (e.g. 100.74.132.81)
# 2. 172.28.0.0/16: The internal Droidspaces NAT bridge (covers all containers)
# 3. YOUR_LAN_SUBNET: Your local Wi-Fi range if using port forwarding (e.g. if your LAN IP is 192.168.1.15, use 192.168.1.0/24)
ignoreip = YOUR_TAILSCALE_IP 172.28.0.0/16 YOUR_LAN_SUBNET

[sshd]
enabled = true
port    = ssh
backend = systemd
```

```bash
systemctl restart fail2ban
fail2ban-client status sshd
```

--------------------------------

### Launch Termux-X11 Server

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/GPU-Acceleration.md

Starts the X server on the host Android device to display container graphics.

```bash
termux-x11 :0
```

--------------------------------

### Combine Volatile and NAT Networking

Source: https://context7.com/ravindu644/droidspaces-oss/llms.txt

Starts a container in volatile mode combined with NAT networking. This setup is ideal for isolated testing environments where changes are temporary and network access is required.

```bash
sudo droidspaces \
  --rootfs-img=/path/to/rootfs.img \
  --name=sandbox \
  --volatile \
  --net=nat \
  --upstream=wlan0 \
  start
```

--------------------------------

### Droidspaces Container Configuration File Example

Source: https://context7.com/ravindu644/droidspaces-oss/llms.txt

An example INI-formatted configuration file for Droidspaces containers. It specifies various settings including name, rootfs, bind mounts, environment files, DNS servers, and boolean flags.

```ini
# Droidspaces Container Configuration
name=ubuntu-server
hostname=ubuntu-devbox
rootfs_path=/var/lib/Droidspaces/Containers/ubuntu/rootfs.img
pidfile=/var/lib/Droidspaces/Pids/ubuntu-server.pid

# Bind mounts (src:dest format, comma-separated)
bind_mounts=/home/user/projects:/workspace,/tmp:/mnt/tmp

# Environment file path
env_file=/path/to/env.list

# DNS servers (comma-separated)
dns_servers=1.1.1.1,8.8.8.8

# UUID (auto-generated, do not modify)
uuid=d88107dab4ef48a8874a93897188982d

# Boolean flags (0 or 1)
disable_ipv6=0
enable_hw_access=0
enable_termux_x11=0
enable_android_storage=0
selinux_permissive=0
volatile_mode=0
foreground=0

```

--------------------------------

### Start Droidspaces with Rootfs Images

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Features.md

Commands for launching containers using image-based root filesystems, including support for volatile read-only mounts.

```bash
# Image-based container (--name is mandatory)
droidspaces --name=ubuntu --rootfs-img=/path/to/rootfs.img start

# Volatile mode with image (image mounted read-only)
droidspaces --name=ubuntu --rootfs-img=/path/to/rootfs.img --volatile start
```

--------------------------------

### Install Droidspaces Binary

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Installation-Linux.md

Extract the downloaded tarball, navigate into the directory, and copy the appropriate binary to /usr/local/bin. Ensure the binary is executable.

```bash
# Extract the tarball
tar xzf droidspaces-v*.tar.gz

# Navigate into the extracted directory
cd droidspaces-v*/

# Copy the binary for your architecture to a directory in your PATH
sudo cp x86_64/droidspaces /usr/local/bin/droidspaces

# Make it executable
sudo chmod +x /usr/local/bin/droidspaces
```

--------------------------------

### Install iw Utility

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Troubleshooting.md

Ensure the `iw` utility is installed in your container. This is required for managing Wi-Fi power save settings.

```shell
apk add iw
```

```shell
apt install iw
```

--------------------------------

### Manage container naming and state

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Troubleshooting.md

Commands to list, scan, and start containers to avoid naming conflicts.

```bash
droidspaces show
```

```bash
droidspaces scan
```

```bash
droidspaces --name=mycontainer-2 --rootfs=/path/to/rootfs start
```

--------------------------------

### Start Volatile Container from Image

Source: https://context7.com/ravindu644/droidspaces-oss/llms.txt

Launches an ephemeral container from a root filesystem image. This is the recommended method for creating temporary testing environments where modifications are not persistent.

```bash
sudo droidspaces \
  --rootfs-img=/path/to/rootfs.img \
  --name=test-env \
  --volatile \
  start
```

--------------------------------

### Install OpenSSH Server

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Cool-things-you-can-do.md

Installs the OpenSSH server package, which is necessary for remote access to your Droidspaces container.

```bash
apt install -y openssh-server
```

--------------------------------

### Start Volatile Container from Directory

Source: https://context7.com/ravindu644/droidspaces-oss/llms.txt

Creates an ephemeral container using OverlayFS, where all changes are stored in RAM and discarded upon exit. The original root filesystem remains unmodified.

```bash
sudo droidspaces \
  --rootfs=/path/to/ubuntu-rootfs \
  --name=throwaway \
  --volatile \
  start
```

--------------------------------

### Print Droidspaces Version

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Linux-CLI.md

Display the installed version string of Droidspaces.

```bash
droidspaces version
```

--------------------------------

### Verify Droidspaces Installation

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Installation-Linux.md

Execute the system requirements checker to ensure Droidspaces is installed correctly and all dependencies are met.

```bash
sudo droidspaces check
```

--------------------------------

### Enable Hardware Access Mode

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Features.md

Command to start a container with hardware access enabled, exposing host devices to the container environment.

```bash
droidspaces --name=gpu-test --rootfs=/path/to/rootfs --hw-access start
```

--------------------------------

### Start Container with Full Hardware Access

Source: https://context7.com/ravindu644/droidspaces-oss/llms.txt

Launches a container with direct access to host hardware devices, including GPUs, USB devices, and sensors. This is enabled using the `--hw-access` flag.

```bash
sudo droidspaces \
  --rootfs=/path/to/rootfs \
  --name=gpu-workstation \
  --hw-access \
  start
```

--------------------------------

### Verify Docker Installation

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Cool-things-you-can-do.md

Run this command to test if Docker can pull and execute a container. A successful run displays 'Hello from Docker!'.

```bash
docker run --rm hello-world
```

--------------------------------

### Identify System Architecture

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Installation-Linux.md

Run this command to determine your system's architecture, which is needed for installing the correct Droidspaces binary.

```bash
uname -m
```

--------------------------------

### Run Docker Inside Droidspaces

Source: https://context7.com/ravindu644/droidspaces-oss/llms.txt

Set up nested containerization by switching to legacy iptables and installing Docker within the container.

```bash
# Start container with NAT networking (required for Docker)
sudo droidspaces \
  --rootfs-img=/path/to/ubuntu.img \
  --name=docker-host \
  --net=nat \
  --upstream=wlan0,rmnet0 \
  start

# Enter container and setup Docker
sudo droidspaces --name=docker-host enter

# Inside container: Switch to legacy iptables (required on Android kernels)
update-alternatives --set iptables /usr/sbin/iptables-legacy
update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

# Test nested container
docker run --rm hello-world
```

--------------------------------

### Configure OpenRC Service for Watchdog

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Troubleshooting.md

Set up the `wifi-watchdog` service for OpenRC init system on Alpine Linux. Ensures the service starts after networking is available.

```shell
#!/sbin/openrc-run

name="WiFi PowerSave Watchdog"
description="Ensures wlan0 power_save stays off"

# Use the path to your loop script
command="/usr/local/bin/wifi-watchdog.sh"

# This tells OpenRC to handle the backgrounding and PID creation
command_background=true
pidfile="/run/${RC_SVCNAME}.pid"

# Ensure it only starts after the network is available
depend() {
    need networking
}
```

--------------------------------

### Get Droidspaces Container Info

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Linux-CLI.md

Display detailed technical information about a specific Droidspaces container.

```bash
sudo droidspaces info
```

--------------------------------

### Start Container with None Networking

Source: https://context7.com/ravindu644/droidspaces-oss/llms.txt

Launches a container in 'none' network mode, creating an air-gapped environment with only a loopback interface. This provides maximum security for offline operations.

```bash
sudo droidspaces \
  --rootfs=/path/to/rootfs \
  --name=airgapped \
  --net=none \
  start
```

--------------------------------

### Set Display for GUI Apps and Verify GPU

Source: https://context7.com/ravindu644/droidspaces-oss/llms.txt

Sets the DISPLAY environment variable inside a container to enable GUI applications and verifies GPU access using `glxinfo`. This is typically done after starting a container with X11 support.

```bash
export DISPLAY=:0
glxinfo | grep "OpenGL renderer"  # Verify GPU access
```

--------------------------------

### Start Container with NAT Networking

Source: https://context7.com/ravindu644/droidspaces-oss/llms.txt

Initiates a container with NAT networking, providing network isolation and internet access. The `--upstream` flag specifies network interfaces for the upstream connection.

```bash
sudo droidspaces \
  --rootfs-img=/path/to/rootfs.img \
  --name=isolated-server \
  --net=nat \
  --upstream=wlan0,rmnet0 \
  start
```

--------------------------------

### Load Droidspaces Configuration from File

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Linux-CLI.md

Specify a configuration file to load container settings directly.

```bash
--conf=PATH
```

--------------------------------

### Create and Mount ext4 Rootfs Images

Source: https://context7.com/ravindu644/droidspaces-oss/llms.txt

Prepare a portable rootfs image by downloading a tarball, formatting a sparse file, and extracting the contents.

```bash
# Download a rootfs tarball
wget https://images.linuxcontainers.org/images/ubuntu/noble/amd64/default/rootfs.tar.xz

# Create a sparse 16GB image file
truncate -s 16G rootfs.img

# Format as ext4
mkfs.ext4 -L Droidspaces rootfs.img

# Mount and extract rootfs
mkdir -p rootfs_mount
sudo mount rootfs.img rootfs_mount
sudo tar -xvf rootfs.tar.xz -C rootfs_mount
sudo umount rootfs_mount
rmdir rootfs_mount

# Boot the container
sudo droidspaces --name=ubuntu --rootfs-img=rootfs.img start
```

--------------------------------

### Networking Modes

Source: https://context7.com/ravindu644/droidspaces-oss/llms.txt

Details on networking modes supported by Droidspaces, with examples for Host Mode Networking.

```APIDOC
## NETWORKING MODES

### Host Mode Networking (Default)

Container shares the host's network stack. Simplest setup with immediate internet access, ideal for most use cases.

### Method
`droidspaces start --net=host` (explicitly)

### Parameters
#### Query Parameters
- `--net` (string) - Optional - Set to `host` to enable host mode networking.

### Request Example
```bash
# Start with host networking (default)
sudo droidspaces --rootfs=/path/to/rootfs --name=webserver start

# Explicitly specify host mode
sudo droidspaces --rootfs=/path/to/rootfs --name=webserver --net=host start
```
```

--------------------------------

### Create Personal User and Set Sudo Privileges

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Cool-things-you-can-do.md

Creates a new user with UID 1000, assigns them a bash shell, adds them to the sudo group, and prompts for a password. Replace YOUR_USER with your desired username.

```bash
useradd -m -u 1000 -s /bin/bash YOUR_USER
usermod -aG sudo YOUR_USER
passwd YOUR_USER
```

--------------------------------

### Merge Configuration with Build System

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Kernel-Configuration.md

Passes the device defconfig and Droidspaces fragments to the make command for automatic merging.

```bash
make [BUILD_OPTIONS] <your_device>_defconfig droidspaces.config droidspaces-additional.config
```

--------------------------------

### Scan for Orphaned Containers

Source: https://context7.com/ravindu644/droidspaces-oss/llms.txt

Detects containers started outside the current session and runs system diagnostics.

```bash
# Scan and recover orphaned containers
sudo droidspaces scan
# Output: Found 2 untracked containers, metadata restored

# Check system requirements
sudo droidspaces check
# Runs 27-point diagnostic on kernel capabilities
```

--------------------------------

### Create and Format Sparse Image for Rootfs

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Installation-Linux.md

This sequence of commands creates a sparse image file, formats it as ext4, and mounts it for extracting the root filesystem. These steps are recommended for better portability.

```bash
# Create a sparse image file (e.g., 16GB):
truncate -s 16G rootfs.img

# Format it as ext4:
mkfs.ext4 -L Droidspaces rootfs.img

# Mount the image:
mkdir -p rootfs_mount
sudo mount rootfs.img rootfs_mount
```

--------------------------------

### Scan for Orphaned Containers

Source: https://context7.com/ravindu644/droidspaces-oss/llms.txt

Detects and registers containers that were started outside the current session or whose metadata was lost.

```APIDOC
## SCAN FOR ORPHANED CONTAINERS

### Description
Detects and registers containers that were started outside the current session or whose metadata was lost.

### Method
`droidspaces scan`

### Parameters
None

### Request Example
```bash
sudo droidspaces scan
```

### Check System Requirements

### Description
Runs a diagnostic check on kernel capabilities required by Droidspaces.

### Method
`droidspaces check`

### Parameters
None

### Request Example
```bash
sudo droidspaces check
```
```

--------------------------------

### Access Droidspaces Documentation

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Linux-CLI.md

Open the interactive, terminal-based documentation for Droidspaces.

```bash
droidspaces docs
```

--------------------------------

### Remove Droidspaces Binary on Linux

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Uninstallation.md

Delete the Droidspaces binary executable from its installation location on a Linux system. The exact path may vary.

```bash
sudo rm /usr/local/bin/droidspaces
```

--------------------------------

### Allow Local Xhost Connections

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/GPU-Acceleration.md

On your host machine, execute this command to permit local containers to connect to your X server.

```bash
xhost +local:
```

--------------------------------

### Flash Vendor Image

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/init/README.md

Use fastboot to flash the repacked vendor image to the device.

```bash
fastboot flash vendor vendor.img
```

--------------------------------

### Configure systemd Service for Watchdog

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Troubleshooting.md

Create a systemd unit file for the `wifi-watchdog` script. This service will restart automatically if it fails.

```ini
[Unit]
Description=WiFi PowerSave Watchdog
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/wifi-watchdog.sh
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Check System Requirements on Linux

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/README.md

Run this command on a Linux desktop to verify if your system meets all the necessary requirements for Droidspaces.

```bash
sudo ./droidspaces check
```

--------------------------------

### NAT with Fixed IP Address

Source: https://context7.com/ravindu644/droidspaces-oss/llms.txt

Starts a container with NAT networking and assigns a fixed IP address. This ensures the container's IP remains consistent across reboots, useful for services requiring static addressing.

```bash
sudo droidspaces \
  --rootfs-img=/path/to/rootfs.img \
  --name=static-server \
  --net=nat \
  --upstream=wlan0 \
  --nat-ip=172.28.5.10 \
  start
```

--------------------------------

### Display Droidspaces Help Message

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Linux-CLI.md

Show the general help message for the Droidspaces CLI.

```bash
droidspaces help
```

--------------------------------

### Configure DNS and systemd-resolved

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Troubleshooting.md

Retrieve ISP DNS addresses and disable the DNS stub listener to resolve connectivity issues.

```shell
dumpsys connectivity | sed 's/}}/\n/g' | grep 'InterfaceName: wlan0' | grep -o 'DnsAddresses: \[[^]]*\]' | grep -o '/[0-9]*\.[0-9]*\.[0-9]*\.[0-9]*' | tr -d '/'
```

```bash
cat > "/etc/systemd/resolved.conf.d/dns.conf" << 'EOF'
[Resolve]
DNSStubListener=no
EOF
```

--------------------------------

### Apply SELinux context to rootfs image

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Troubleshooting.md

Manually set the correct SELinux context for loop-mounting rootfs images on older Droidspaces versions.

```bash
chcon u:object_r:vold_data_file:s0 /path/to/rootfs.img
```

--------------------------------

### Switch to iptables-legacy

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Cool-things-you-can-do.md

Commands to switch the networking backend to legacy to avoid chain errors in nested containers.

```bash
update-alternatives --set iptables /usr/sbin/iptables-legacy
update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy
```

--------------------------------

### Manage Container Lifecycle and System Checks

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Linux-CLI.md

Commands for recovering containers and verifying system requirements.

```bash
sudo droidspaces scan
```

```bash
sudo droidspaces check
```

--------------------------------

### Define Droidspaces Configuration File

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Linux-CLI.md

Use an INI-style configuration file to define container environments instead of long command-line arguments.

```ini
# Droidspaces Container Configuration
# Generated automatically - Changes may be overwritten

# Unique identifier for the container
name=ubuntu

# Hostname of the container environment
hostname=ubuntu-devbox

# Absolute path to the rootfs directory or .img file
rootfs_path=/home/user/ubuntu-24.04-rootfs.img

# Custom path to store the container's PID file
pidfile=/var/lib/Droidspaces/Pids/ubuntu.pid

# Comma-separated list of host directories to bind mount (src:dest)
bind_mounts=/home/user:/mnt/host,/tmp:/mnt/tmp

# Absolute path to a file containing environment variables to load
env_file=/path/to/env.list

# Unique UUID (Automatically generated, do not change manually)
uuid=d88107dab4ef48a8874a93897188982d

# Custom DNS servers (comma separated)
dns_servers=1.1.1.1,8.8.8.8

# -------- Boolean Flags (0 or 1) --------

# Disable IPv6 networking
disable_ipv6=0

# Expose host hardware nodes to the container (/dev)
enable_hw_access=0

# Android: Setup Termux X11 socket
enable_termux_x11=0

# Android: Setup Android internal shared storage mount
enable_android_storage=0

# Set the host SELinux policy to permissive during boot
selinux_permissive=0

# Ephemeral mode: changes are lost on exit
volatile_mode=1

# Run the container in the foreground instead of forking
foreground=0

# ----------------------------------------
# Android App Configuration
# Any lines that the CLI engine does not recognize will be safely
# preserved at the bottom of the config file and passed back to the Host.
```

--------------------------------

### Configure UFW Firewall

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Cool-things-you-can-do.md

Commands to disable IPv6, set default policies, whitelist the Tailscale interface, and enable the firewall.

```bash
sed -i 's/IPV6=yes/IPV6=no/' /etc/default/ufw
```

```bash
ufw default deny incoming
ufw default allow outgoing
```

```bash
ufw allow in on tailscale0
```

```bash
ufw --force enable
```

--------------------------------

### Deploy Secure Mobile Server with Tailscale

Source: https://context7.com/ravindu644/droidspaces-oss/llms.txt

Configure a remote-accessible server using Tailscale and UFW firewall rules inside a Droidspaces container.

```bash
# Start container with NAT networking
sudo droidspaces \
  --rootfs-img=/path/to/ubuntu.img \
  --name=mobile-server \
  --net=nat \
  --upstream=wlan0,rmnet0 \
  --port=22:22 \
  start

# Enter and configure
sudo droidspaces --name=mobile-server enter

# Inside container: Install and configure Tailscale
apt update && apt install -y openssh-server iptables net-tools
update-alternatives --set iptables /usr/sbin/iptables-legacy
curl -fsSL https://tailscale.com/install.sh | sh
tailscale up

# Configure UFW firewall
apt install -y ufw
sed -i 's/IPV6=yes/IPV6=no/' /etc/default/ufw
ufw default deny incoming
ufw default allow outgoing
ufw allow in on tailscale0
ufw --force enable

# Now accessible from anywhere via Tailscale IP
```

--------------------------------

### Show Container Status and Info

Source: https://context7.com/ravindu644/droidspaces-oss/llms.txt

Displays information about running containers, including status, PID, and uptime.

```bash
# List all running containers
sudo droidspaces show
# Output:
# NAME          STATUS    PID     UPTIME
# ubuntu        running   12345   2h 15m
# devbox        running   12456   45m

# Show status of specific container
sudo droidspaces --name=ubuntu status

# Show detailed container information
sudo droidspaces --name=ubuntu info
# Output includes: rootfs path, hostname, IP, networking mode, bind mounts, etc.

# Show container uptime
sudo droidspaces --name=ubuntu uptime
```

--------------------------------

### Verify and Configure GPU Access

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Troubleshooting.md

Commands to inspect GPU group membership and manually configure device access if automatic detection fails.

```bash
droidspaces --name=mycontainer enter
cat /etc/group | grep gpu_
```

```bash
ls -la /dev/dri/ /dev/kgsl-3d0 /dev/mali0 2>/dev/null
```

```bash
groupadd -g <GID> gpu_custom
usermod -aG gpu_custom root
```

```bash
termux-x11 :0 &
export DISPLAY=:0
ls -la /tmp/.X11-unix/
```

--------------------------------

### Enter a Container

Source: https://context7.com/ravindu644/droidspaces-oss/llms.txt

Opens an interactive shell session inside a running container.

```bash
# Enter as root (default)
sudo droidspaces --name=ubuntu enter

# Enter as a specific user
sudo droidspaces --name=ubuntu enter developer

# Enter the only running container (auto-detection)
sudo droidspaces enter
```

--------------------------------

### Check Droidspaces Requirements

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Kernel-Configuration.md

Execute this command in a terminal to verify that the kernel meets all necessary requirements for container support.

```bash
su -c droidspaces check
```

--------------------------------

### Restart Container with Sync

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Troubleshooting.md

Force a filesystem sync before restarting a container to resolve race conditions on older kernels.

```bash
sync && droidspaces --name=mycontainer restart
```

--------------------------------

### Multiple Bind Mounts (Comma-Separated)

Source: https://context7.com/ravindu644/droidspaces-oss/llms.txt

Configures multiple bind mounts using a comma-separated list with the `-B` or `--bind-mount` flag. This allows mapping several host directories into the container simultaneously.

```bash
sudo droidspaces \
  --rootfs=/path/to/rootfs \
  --name=dev \
  -B /home/user/projects:/workspace,/home/user/data:/data \
  start
```

--------------------------------

### Resolve OverlayFS f2fs incompatibility

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Troubleshooting.md

Use an ext4 image instead of a directory when the underlying filesystem is f2fs.

```bash
# This will fail on f2fs:
droidspaces --rootfs=/data/rootfs --volatile start

# This will work (ext4 image provides a compatible lower directory):
droidspaces --name=test --rootfs-img=/data/rootfs.img --volatile start
```

--------------------------------

### List Running Droidspaces Containers

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Linux-CLI.md

View a table of all currently running Droidspaces containers.

```bash
sudo droidspaces show
```

--------------------------------

### Configure Manual Bind Mounts for GPU Nodes

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/GPU-Acceleration.md

Add these mappings to your container's Custom Bind Mounts section to manually expose specific GPU device nodes.

```text
/dev/dri/renderD128:/dev/dri/renderD128
/dev/kgsl-3d0:/dev/kgsl-3d0
/dev/dma_heap/system:/dev/dma_heap/system
/dev/ion:/dev/ion (Optional: skip if /dev/ion does not exist on your host)
```

--------------------------------

### Configure VirGL Environment Variables

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/GPU-Acceleration.md

Required environment variables to enable VirGL hardware acceleration within the container.

```bash
DISPLAY=:0
GALLIUM_DRIVER=virpipe
```

--------------------------------

### Make Watchdog Script Executable

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Troubleshooting.md

Set execute permissions for the watchdog script.

```shell
chmod +x /usr/local/bin/wifi-watchdog.sh
```

--------------------------------

### Multiple Bind Mounts (Chained)

Source: https://context7.com/ravindu644/droidspaces-oss/llms.txt

Applies multiple bind mounts by chaining the `-B` or `--bind-mount` flag for each mount point. This provides flexibility in specifying various host directories to be accessible within the container.

```bash
sudo droidspaces \
  --rootfs=/path/to/rootfs \
  --name=dev \
  -B /home/user/projects:/workspace \
  -B /home/user/.ssh:/root/.ssh \
  -B /tmp:/mnt/host-tmp \
  start
```

--------------------------------

### Demonstrate Memory Offset Shift in Kernel Structures

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Kernel-Configuration.md

Illustrates how adding a variable to a kernel structure shifts memory offsets, causing binary incompatibility with pre-compiled modules.

```c
struct b {
    int varX;  // Offset: 0x0 (32-bit)
    long varY; // Offset: 0x20 (64-bit)
    long varZ; // Offset: 0x60 (64-bit)
};
```

```c
struct b {
    int varX;  // Offset: 0x0
    int varC;  // Offset: 0x20 (NEW VARIABLE)
    long varY; // Offset: 0x40 (SHIFTED!)
    long varZ; // Offset: 0x80 (SHIFTED!)
};
```

--------------------------------

### Hardware Access with X11 for GUI Apps

Source: https://context7.com/ravindu644/droidspaces-oss/llms.txt

Enables hardware access and configures the container to use X11 sockets for GUI applications, commonly used with Android and Termux-X11. Requires `--termux-x11` flag.

```bash
sudo droidspaces \
  --rootfs=/path/to/rootfs \
  --name=desktop \
  --hw-access \
  --termux-x11 \
  start
```

--------------------------------

### Configure Droidspaces DNS

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Linux-CLI.md

Specify custom DNS servers for a Droidspaces container.

```bash
--dns=SERVERS
```

--------------------------------

### Locate Kernel Configuration Fragments

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Kernel-Configuration.md

Indicates the required directory structure for placing configuration files within the kernel source tree.

```bash
# For ARM64 devices, place them alongside your device defconfig:
# $KERNEL_ROOT/arch/arm64/configs/droidspaces.config
# $KERNEL_ROOT/arch/arm64/configs/droidspaces-additional.config  (optional)
```

--------------------------------

### X11 Only Without Full Hardware Access

Source: https://context7.com/ravindu644/droidspaces-oss/llms.txt

Configures a container to use X11 for GUI applications without granting full hardware access. This provides a safer environment for running GUI applications when direct hardware interaction is not needed.

```bash
sudo droidspaces \
  --rootfs=/path/to/rootfs \
  --name=gui-apps \
  --termux-x11 \
  start
```

--------------------------------

### Restart a Container

Source: https://context7.com/ravindu644/droidspaces-oss/llms.txt

Performs a fast restart (under 200ms) by preserving loop mounts and coordinating state. Ideal for applying configuration changes.

```APIDOC
## RESTART CONTAINER

### Description
Performs a fast restart (under 200ms) by preserving loop mounts and coordinating state. Ideal for applying configuration changes.

### Method
`droidspaces restart`

### Parameters
#### Path Parameters
None

#### Query Parameters
- `--name` (string) - Required - Name of the container to restart.
- `--conf` (string) - Optional - Path to the container configuration file.

### Request Example
```bash
sudo droidspaces --name=ubuntu restart
sudo droidspaces --conf=/var/lib/Droidspaces/Containers/ubuntu/container.config restart
```
```

--------------------------------

### Enable Termux-X11 Support in Droidspaces

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Linux-CLI.md

Mount the X11 socket to enable graphical applications using Termux-X11 on Android.

```bash
--termux-x11
```

--------------------------------

### Configure Droidspaces Networking

Source: https://context7.com/ravindu644/droidspaces-oss/llms.txt

Define networking modes, upstream interfaces, and port forwarding rules in the configuration file.

```ini
net_mode=nat
upstream_ifaces=wlan0,rmnet0
port_forwards=22:22/tcp,80:8080/tcp
static_nat_ip=172.28.5.10
```

--------------------------------

### Single Bind Mount

Source: https://context7.com/ravindu644/droidspaces-oss/llms.txt

Mounts a host directory into the container at a specified path. The format is `host_path:container_path`. This allows persistent data or code sharing between host and container.

```bash
sudo droidspaces \
  --rootfs=/path/to/rootfs \
  --name=dev \
  --bind-mount=/home/user/projects:/workspace \
  start
```

--------------------------------

### Configure Droidspaces Container Hostname

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Linux-CLI.md

Set a custom hostname for the Droidspaces container. Defaults to the container's name.

```bash
--hostname=NAME
```

--------------------------------

### Show Container Status and Info

Source: https://context7.com/ravindu644/droidspaces-oss/llms.txt

Displays running container information including status, PID, uptime, and detailed technical information.

```APIDOC
## SHOW CONTAINER STATUS AND INFO

### Description
Displays running container information including status, PID, uptime, and detailed technical information.

### Method
`droidspaces show`

### Parameters
#### Path Parameters
None

#### Query Parameters
- `--name` (string) - Optional - Name of the container to show status/info for.
- `status` - Optional - Alias for showing only the status.
- `info` - Optional - Alias for showing detailed information.
- `uptime` - Optional - Alias for showing only the uptime.

### Request Example
```bash
sudo droidspaces show
sudo droidspaces --name=ubuntu status
sudo droidspaces --name=ubuntu info
sudo droidspaces --name=ubuntu uptime
```

### Response
#### Success Response (200)
- **NAME** (string) - Name of the container.
- **STATUS** (string) - Current status of the container (e.g., running).
- **PID** (integer) - Process ID of the container's init process.
- **UPTIME** (string) - How long the container has been running.

#### Response Example (for `show` command)
```json
{
  "NAME": "ubuntu",
  "STATUS": "running",
  "PID": 12345,
  "UPTIME": "2h 15m"
}
```

#### Response Example (for `info` command)
```json
{
  "rootfs_path": "/path/to/rootfs",
  "hostname": "ubuntu-devbox",
  "ip_address": "10.0.2.15",
  "networking_mode": "host",
  "bind_mounts": [],
  "...": "..."
}
```
```

--------------------------------

### Droidspaces Kernel Configuration

Source: https://github.com/ravindu644/droidspaces-oss/blob/main/Documentation/Usage-Android-App.md

This is a sample kernel configuration snippet for Droidspaces, specific to your device. Copy this configuration from the Settings panel.

```text
droidspaces.config
```