Skip to content

Latest commit

 

History

History
334 lines (256 loc) · 11.4 KB

Linux-CLI.md

File metadata and controls

334 lines (256 loc) · 11.4 KB

Linux CLI Guide

Complete guide to using Droidspaces from the command line on Linux.

Tip

Using the CLI on Android: All command-line arguments work exactly the same on Android.

Once the backend is installed via the app, the droidspaces binary is located at /data/local/Droidspaces/bin/droidspaces.

Also, you can view the full interactive, more advanced command-line documentation offline at any time by running: droidspaces docs


Quick Navigation

1. Getting Started
2. Command Reference
3. Options & Flags
4. Configuration Files
5. Common Workflows
6. Advanced Usage & Lifecycle
7. System Requirements


1. Getting Started

Start Your First Container

# From a rootfs directory
sudo droidspaces --rootfs=/path/to/rootfs start

# From an ext4 image
sudo droidspaces --name=mycontainer --rootfs-img=/path/to/rootfs.img start

Enter the Container

# Enter as root
sudo droidspaces --name=mycontainer enter

# Enter as a specific user
sudo droidspaces --name=mycontainer enter username

Stop the Container

# Stop a single container
sudo droidspaces --name=mycontainer stop

# Stop multiple containers
sudo droidspaces --name=web,db,app stop

2. Command Reference

Command Action
start Start a new container. Requires either --rootfs or --rootfs-img.
stop Gracefully shut down one or more containers.
restart Fast restart (under 200ms) by preserving loop mounts.
enter [user] Open an interactive shell inside a running container.
run <cmd> Execute a single command without opening a full shell. Use -u/--user to run as a specific container user.
info Show deep technical details about a container.
show List all currently running containers in a table.
scan Detect and register orphaned/untracked containers.
check Verify system and kernel requirements.
docs Open the interactive terminal-based documentation.
help Display the help message.
version Print the version string.

3. Options & Flags

Rootfs Selection

Option Short Description
--rootfs=PATH -r Path to a rootfs directory. Must contain /sbin/init.
--rootfs-img=PATH -i Path to an ext4 rootfs image file or block device. Automatically mounted.

Note: These are mutually exclusive. --name is mandatory when using --rootfs-img.

Container Identity & Configuration

Option Short Description
--name=NAME -n Unique name for the container. Auto-generated if omitted in directory-based rootfs mode.
--hostname=NAME -h Set the container's hostname. Defaults to the container name.
--conf=PATH -C Load container configuration directly from a config file.
--reset Reset container config to defaults (preserves name, rootfs path).

Networking

Option Short Description
--net=MODE Networking mode: host (default), nat, none, or gateway.
--upstream=IFACE Pin the NAT WAN to specific interface(s); disables automatic uplink detection. Comma-separated, priority-ordered, supports wildcards. Example: --upstream=wlan0,rmnet*. NAT mode only.
--port HOST:CONT[/proto] Forward host port to container (NAT mode). Supports TCP/UDP.
--dns=SERVERS -d Custom DNS servers, comma-separated. Example: --dns=1.1.1.1,8.8.8.8
--disable-ipv6 Disable IPv6 networking support (Host mode only).

Gateway Mode

Delegate a container's LAN to another running container (e.g. OpenWRT), which then owns DHCP, DNS, firewall and routing. Droidspaces only does the L2 plumbing. See Networking From Zero for the full guide.

Option Short Description
--gateway=NAME Required for --net=gateway. The running container that acts as the router.
--gateway-net=NAME LAN segment name / host bridge suffix (default: lan). Clients sharing a value share a LAN; different values are isolated segments.
--gateway-iface=IFACE Interface name as seen inside the gateway container (default: eth1). Each segment needs a unique name.
--gateway-bridge=BR Override the host bridge name (default: ds-{gateway-net}).

Feature Flags

Option Short Description
--foreground -f Attach to the container console on start to see init logs.
--volatile -V Ephemeral mode. Changes are stored in RAM and lost on exit.
--hw-access -H Expose host hardware (GPU, USB, etc.). Auto-detects GPU group IDs and creates matching groups inside the container. Mounts X11 socket for GUI apps (Termux X11 on Android, /tmp/.X11-unix on Linux). See Safety Warning.
--gpu Exclusively enable GPU acceleration. Scans the host /dev for known GPU nodes and securely maps only them into the container without exposing other host hardware. (Ignored if -H is passed).
--termux-x11 -X Mount X11 socket for Termux-X11 display (Android only).
--enable-android-storage Mount /storage/emulated/0 (Android only).
--selinux-permissive Set host SELinux to permissive for the container session.
--force-cgroupv1 Force legacy Cgroup V1 hierarchy. Required if the host kernel has a broken or partial Cgroups V2 implementation (common on older Android 4.x kernels).
--privileged=TAGS Relax security protections. Accepts a comma-separated list of tags: nomask, nocaps, noseccomp, shared, unfiltered-dev, full. Use with extreme caution.

Bind Mounts

Option Short Description
--bind-mount=S:D -B Mount a host directory S to container path D.

Formats:

  • Multiple mounts: -B /src1:/dst1,/src2:/dst2 or -B /src1:/dst1 -B /src2:/dst2
  • Max limits: Up to 16 mounts per container.
  • Missing host paths are skipped with a warning.

4. Configuration Files

Instead of relying solely on long command-line arguments, Droidspaces allows you to define container environments in a .config file and load it using the --conf flag.

Below is a reference of every supported key in the configuration file:

# 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

# Auto-detect and securely map GPU nodes without full hardware access
enable_gpu_mode=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.

5. Common Workflows

Running with a Config File

Instead of passing many flags, you can load everything from a .config file:

sudo droidspaces --conf=./my-container.config start

Persistent Development

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

NAT Isolation with Port Forwarding

sudo droidspaces \
  --name=server \
  --rootfs-img=/path/to/rootfs.img \
  --net=nat \
  --port=8080:80 \
  start

NAT with a Pinned Uplink

Force the container's internet out through a specific interface instead of following the host's active network. Pin a VPN tunnel (tun0) as a killswitch, or rmnet* to stay on mobile data while the phone uses Wi-Fi:

sudo droidspaces \
  --name=vpnbox \
  --rootfs-img=/path/to/rootfs.img \
  --net=nat \
  --upstream=tun0 \
  start

Gateway Mode (LAN owned by OpenWRT)

Start the router container first (in NAT mode), then attach clients to it:

# 1. the router
sudo droidspaces --name=openwrt --rootfs=/data/openwrt --net=nat start

# 2. a client whose LAN/DHCP/firewall is owned by openwrt
sudo droidspaces --name=kali --rootfs=/data/kali --net=gateway --gateway=openwrt start

Ephemeral Testing

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

One-Off Commands

sudo droidspaces --name=mycontainer run uname -a
# Use sh -c for pipes:
sudo droidspaces --name=mycontainer run sh -c "ps aux | grep init"
# Run as a specific user with -u/--user:
sudo droidspaces --name=mycontainer -u myuser run whoami
sudo droidspaces --name=mycontainer -u myuser run env
sudo droidspaces --name=mycontainer -u myuser run sh -c "id && env"

GPU Acceleration

Ensure only the GPU nodes (and not all host hardware) are securely exposed:

sudo droidspaces --name=gpu-app --rootfs=/path/to/rootfs --gpu start

Deep Customization (Privileged Mode)

For cases where you need unmasked access:

sudo droidspaces --name=privileged-box --rootfs=/path/to/rootfs --privileged=full start
# Or mix and match tags:
sudo droidspaces --name=dev-box --rootfs=/path/to/rootfs --privileged=nocaps,noseccomp start

6. Advanced Usage & Lifecycle

Container Recovery

If a container was started outside the current session, or its host-side PID file / config file was lost or corrupted, use scan to resurrect it from the container's isolated /run memory:

sudo droidspaces scan

7. System Requirements

Always run the built-in checker to verify your kernel supports the required namespaces and features:

sudo droidspaces check

See the Kernel Configuration Guide for a deep dive into technical requirements.


Next Steps