Command line reference #

The droidspaces binary is the same on Linux and Android, and so are its commands and flags. On Android the app installs it at /data/local/Droidspaces/bin/droidspaces, and the Integrate Droidspaces to the system path setting puts it on the PATH of root shells.

Flags and the command can come in any order, short and long forms are interchangeable, and = is optional: droidspaces -n web start and droidspaces start --name=web are the same. droidspaces docs shows the same reference in a pager, offline.

Commands #

Every command except check, docs, help, version and mode needs root. When exactly one container is running, --name can be left out of stop, restart, enter, run, info and pid.

If a daemon is running, the CLI hands the command to it, so members of the droidspaces group can use the CLI without sudo. DS_NO_PROXY=1 in the environment makes the binary do the work itself.

Flags #

Each flag that configures the container is saved in its config file on start, so it only has to be given once. Container settings explains what each one does and when to use it; this table is the syntax.

Rootfs and identity

Networking

Hardware and integration

Resource limits, security and boot

Session flags, not saved

The config file #

A plain key=value file, one key per line, with the keys from the tables above. Droidspaces looks for it in this order: the file named by --config, then container.config next to the rootfs, then Containers/<name>/container.config in the workspace. The workspace is /var/lib/Droidspaces on Linux and /data/local/Droidspaces on Android.

name=web
hostname=web
rootfs_path=/var/lib/Droidspaces/Containers/web/rootfs.img
net_mode=nat
port_forwards=80:80,443:443
bind_mounts=/srv/www:/var/www:ro
memory_limit=1073741824
cpu_quota=200000
cpu_period=100000
allow_sandboxing=1

Boolean keys take 0 or 1. Keys the backend does not know, such as the app's run_at_boot, are kept in place. While a container runs, the config it booted with is visible inside it at /run/droidspaces/container.config.

Examples #

# A first container from an image, with a port forwarded
sudo droidspaces --name=web --rootfs-img=/srv/web.img --port=8080:80 start

# Later starts need only the name
sudo droidspaces --name=web start

# Watch the boot on the console
sudo droidspaces --name=web --foreground start

# A shell as a user, and a one-off command with a pipe
sudo droidspaces --name=web enter alice
sudo droidspaces --name=web run sh -c 'ps aux | grep nginx'

# A script piped into the container
sudo droidspaces --name=web --stdin run sh -s < setup.sh

# An OpenWrt router and a client that lives behind it
sudo droidspaces --name=openwrt --rootfs=/srv/openwrt --net=nat start
sudo droidspaces --name=kali --rootfs=/srv/kali --net=gateway --gateway=openwrt start

# A container on the wired LAN with its own address
sudo droidspaces --name=ubuntu --rootfs=/srv/ubuntu --net=macvlan --macvlan-parent=eth0 start

# Try something without keeping it
sudo droidspaces --name=scratch --rootfs=/srv/ubuntu --volatile start

# What is running, as JSON
sudo droidspaces --format show

Where things are #

Previous: Container settings | Next: Display, audio and desktop