lxcd/README.md

lxcd

A Distrobox-like wrapper for LXD: it creates, manages, and enters LXD dev containers as drop-in development environments, mapped to your host workspace and home.

Requirements

• LXD (lxc) reachable on your host — either the user is in the lxd group (invoked directly) or sudo lxc is used
• Python 3.9+
• Bash completion (optional): lxcd.completion

Install

sudo ./setup.sh                  # copies lxcd.py to /usr/local/bin/lxcd + installs completion

setup.sh needs root only to write to /usr/local/bin and /etc/bash_completion.d; for a user-local install instead:

BIN_DIR=~/.local/bin COMPLETION_DIR=~/.bash_completion.d ./setup.sh

If you use GNU Make you can also run make install (same thing, delegates to setup.sh).

Or run in place from this directory:

./lxcd.py --help

Quick start

lxcd init                     # write ~/.lxcdrc (never shown; edit with -e)
lxcd init -e                  # open the config in $EDITOR, created first if missing

lxcd create web1              # new container "web1" (defaults from ~/.lxcdrc)
lxcd ls                       # alias for "list"
lxcd enter web1               # cloud-init workspaces + mappings auto-applied

Commands

Command	Description
init	Write/edit the ~/.lxcdrc config
create	Create a new container (defaults from config)
clone <src> <name>	Clone an existing managed container
rename|mv <old> <new>	Rename a container
enter <name>	Enter a container (applies workspace + mappings)
list|ls	List managed containers
delete|stop|start|restart	Operate on containers (-a for all)

Run lxcd <command> --help for full options.

Config (~/.lxcdrc)

INI format. Keys:

• [options] — workspace, image, nested, aptcache, ssh (absolute paths OK for workspace/image when used as-is)
• [packages] — default apt packages installed at create time
• [mappings] under [options] or top-level — a list of host paths to mount into every container. A spec ending in / mounts a directory; an absolute host path (starting with /) is used as-is (not relative to ~) and mounts at the same path in the container.

Example:

[options]
workspace=/home/andrew/Code    # absolute — mounted as-is
image=ubuntu:
nested=true
aptcache=http://10.0.0.1:3142
ssh=ssh-ed25519 AAAA...andrew@host

[packages]
git
vim

[mappings]
configs/       # directory: ~/configs -> /home/<user>/configs/
notes          # file: ~/notes -> /home/<user>/notes
/etc/hosts     # absolute: used as-is

Conventions

• Containers are tagged with user.lxcd=true for listing.
• security.nesting is enabled when nested=true (cli -n/--nested).
• Disk mounts use shift=true so container writes map cleanly to the host.
• enter mounts the [options] workspace= host dir into the container and applies [mappings] before running an interactive shell as the host user.

Completion

lxcd.completion (bash). Keep it sourced for container-name + option completion, including lxcd list --brief [cols].

Building a snap

snapcraft --destructive-mode -v

produces lxcd_0.1.0_amd64.snap (version pinned in snap/snapcraft.yaml).

License

MIT.