bsdev

bsdev launches and connects to a permanently-running Arch Linux dev container, from any shell on any OS.

Note

Built for Brownserve projects and conventions, may have limited use outside of that context.

The container comes with:

• git
• GitHub CLI
• chezmoi
• fish
• oh-my-posh
• topgrade
• Node.js / npm
• Rust (via rustup)
• tenv
• Claude Code
• JDK
• Android SDK

Install

Grab the latest release and run the installer for your platform:

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/Brownserve-UK/bsdev/main/scripts/install.sh | bash

# Windows
irm https://raw.githubusercontent.com/Brownserve-UK/bsdev/main/scripts/install.ps1 | iex

Both scripts download the right binary for your OS/architecture from the latest release and put it on your PATH.

Usage

Just run bsdev. On first run it creates an SSH key, pulls the image and starts the container; every run after that just connects you. code . inside the container opens the folder in your host's VSCode - no config needed, just the Dev Containers extension installed.

Usage: bsdev [OPTIONS] [COMMAND]

Commands:
  update   Update bsdev to the latest published release
  up       Ensure the image and container are up, without connecting
  down     Stop the container (its home volume is preserved)
  status   Show image, container and home volume state
  rebuild  Pull the latest image and recreate the container (keeps the home volume)
  repos    Get or persist the host directory bind-mounted at ~/host-repos
  adb      Get or persist the host adb server port forwarded into the container
  forward  Forward a host port to the same port inside the container

Options:
  -v, --verbose  Print each docker/ssh command as it runs
  -h, --help     Print help
  -V, --version  Print version

Updating

Run bsdev update to check GitHub for the latest published release and replace the installed executable after confirmation. For non-interactive use, pass --yes (or -y) to skip the prompt:

bsdev update --yes

If bsdev was installed system-wide, the command will explain that it needs to be rerun with sudo on Linux/macOS or from an Administrator terminal on Windows. Updates are only checked when this command is run; normal bsdev usage does not make update requests.

If you want code changes made inside the container reachable from the host (e.g. to run integration tests in host VMs), point bsdev at a host directory; it's bind-mounted at ~/host-repos in the container. Persist it once with bsdev repos <path> so you don't have to set it every run, or set BSDEV_REPOS to override it for a single run (bsdev repos --unset clears the persisted value, bsdev repos with no arguments shows it). This is optional and off by default - a plain host directory can't hold Unix symlinks on Windows, so a repo relying on those should live in a WSL2/Linux-backed path instead.

For Android dev, bsdev adb [<port>] (default 5037) forwards your host's adb server into the container over a dedicated background ssh tunnel, so adb inside the container reaches devices attached to the host - this keeps working even in a VSCode terminal after you've closed the terminal bsdev was launched from. Requires adb start-server already running on the host. Off by default; bsdev adb --unset disables it, and bsdev adb with no arguments shows the current port.

Building

Requires the Rust toolchain and PowerShell 7+.

./.build/build.ps1 -Build BuildTestAndCheck

See CONTRIBUTING.md for more.