Infrastructure management, from one machine to your whole network.
The command is basaltw and the Python entry point is basaltwater.py.
Only the Basaltwater namespace is supported. The completed infra-tools
migration is retired; remaining old installations must use the documented
intermediate version first.
The identity guide includes editable assets and visual specimens.
Automated setup and operations for Debian control planes, servers, workstations, and Proxmox guests. Basaltwater applies repeatable, machine-aware configuration over SSH, stores redacted setup state in a workspace, and provides targeted operations for hosts that are already configured.
This checkout is preparing the v2.0.0 release-candidate series. Its current
package version is 2.0.0rc1; preview tags use v2.0.0-rc.N and publish as
GitHub prereleases. Until a preview tag is published, the installer’s dev
channel tracks main. Preview tags are opt-in; stable continues to select the
latest final release until v2.0.0 passes qualification and is published.
New to Linux or Basaltwater? Follow Try Basaltwater on a Debian VM for a guided first setup, small feature experiments, and checks that show whether each step worked.
Install the launcher on the machine that will manage your hosts:
sh -c '
installer=$(mktemp) || exit
cleanup() { rm -f -- "$installer"; }
trap cleanup EXIT
curl -fsSL --max-time 120 https://raw.githubusercontent.com/bluehexagons/basaltwater/main/install.sh -o "$installer" &&
sh "$installer" "$@"
' shCopy the whole block; it works in fish, Bash, and Zsh. The explicit sh
invocation handles the temporary download and removes it on exit.
If curl is missing, use the download prerequisites.
Installing the launcher does not configure a target. Use basaltw setup ... for
remote hosts and basaltw upgrade to update the selected channel. The
basaltw refresh command upgrades
Basaltwater and repeats this machine's last successful setup: use sudo on
Debian and the desktop account without sudo on CachyOS. The
installation guide covers prerequisites, verification,
alternate download commands, local control-plane and desktop/RDP profiles,
channels, credentials, and recovery. The documentation index
organizes detailed feature and operations guides.
Contributors should also read the contributor and coding-agent guide before changing the project.
Basaltwater officially supports Debian on:
- bare-metal systems;
- virtual machines, including Proxmox-provisioned VMs; and
- unprivileged Debian LXC containers on Proxmox.
The installer and setup preflight also recognize Ubuntu and Linux Mint as best-effort Debian-compatible environments. Debian remains the only officially supported distribution.
An experimental, limited CachyOS + KDE coding profile adds agent tooling to an existing bare-metal workstation through local self-setup. It preserves the human account and desktop, leaves OS updates to CachyOS/the user, and does not support CachyOS VM/container provisioning or server setup.
For your first Codex setup with the native T3 Code desktop app, use the complete CachyOS installer example. The guide uses fish, CachyOS's default shell, and walks through selecting tools, installing the launcher, provider login, and checking the first coding task.
The normal direct setup path uses --machine auto. Hosted Proxmox setup
defaults to a VM; select --machine unprivileged for the supported LXC path.
See Machine types for capability and compatibility
details.
Choose the row for the workload you will actually run. Each cell lists CPU cores / RAM / total OS disk; for a VM, cores means virtual CPUs. These are practical planning tiers for Debian, not installer-enforced limits or benchmarks of every feature combination. Minimum means one user doing limited work, recommended suits ordinary small deployments, and performance adds room for concurrency, larger builds, and retained caches.
| Use case | Minimum | Recommended | Performance |
|---|---|---|---|
| Controller or light SSH/server utilities | 1 / 1 GB / 8 GB | 2 / 2 GB / 16 GB | 4 / 4 GB / 32 GB |
| Small web server or file-sharing service | 1 / 1 GB / 16 GB | 2 / 2 GB / 32 GB | 4 / 8 GB / 64 GB |
| Headless development with one language runtime or coding agent | 2 / 2 GB / 16 GB | 2 / 4 GB / 32 GB | 4 / 8 GB / 64 GB |
| Full XFCE/RDP desktop, T3, and occasional browser testing | 2 / 4 GB / 32 GB | 4 / 8 GB / 64 GB | 8 / 16 GB / 128 GB |
| Godot development, frequent builds, or several concurrent agents | 2 / 4 GB / 32 GB¹ | 4 / 8 GB / 64 GB | 8+ / 16–32 GB / 128–256 GB |
¹ The minimum covers small 2D projects or one build/agent at a time; concurrent agents and large projects need more memory and storage. CPU speed, SSD latency, and graphics support also affect performance. Extra disk capacity alone does not make a machine faster.
A 32 GB full desktop is a valid limited-use target. Keep only a few small projects locally, limit browser tabs and parallel builds, and leave recurring cleanup enabled. Budget roughly 4–6 GB of available space for temporary downloads and updates; cleanup can discard rebuildable caches but cannot shrink your projects or remove files used by active tools. Our maintained 32 GB test VM runs the desktop and agent/browser tooling at about 23 GiB used after managed cleanup (September 2026); this is an observed footprint, not a fresh-install size guarantee.
The disks above include Debian, selected tools, modest local work, and room for updates. Add space for shared files, databases, container images, media, and backups separately. Minimum-memory setups assume swap is available; allow about 2 GB for light servers and 4 GB for the desktop within the disk budget. Swap helps with brief memory spikes but does not replace RAM for sustained work. Coding-agent rows assume remote model providers; local model inference needs its own RAM, accelerator, and model-storage budget. These sizes exceed Debian's base installation requirements to accommodate Basaltwater and useful work. For Proxmox hosts, add the resources required by every guest and storage workload to the host's own requirements; the table describes individual guests, not an entire virtualization host.
Start with 64 GB for a desktop when unsure; choose 128 GB for the performance tier or substantial local work. The beginner walkthrough and cleanup guide explain how to try features and keep a small VM usable.
| Area | Summary | Detailed guide |
|---|---|---|
| Setup and CLI | Unified setup, patch, shares, saved-host operations, and utility commands |
Command-line reference |
| Installation | User/system bootstrap, orchestration host prerequisites, and completion | Installation |
| Firmware | Local fwupd inventory, dependency installation, and deliberate guarded updates | Firmware |
| Control planes | Local VM/container administration tools, SSH/rsync, diagnostics, and optional coding agents | Installation, Agent systems, Quick reference |
| Servers | Security hardening, Nginx/SSL, Cloudflare tunnels, language runtimes, deployments, Gogs, and Antistatic | CLI reference, Gogs, Cloudflare tunnels, Antistatic |
| Workstations | XFCE, i3, LXQt, RDP, browsers, and desktop tooling | Workstations, XRDP, CLI reference |
| CachyOS coding | Codex on an existing KDE workstation; T3 desktop or a local/LAN web service, plus setup-time cache cleanup | CachyOS |
| Storage | Authenticated Samba shares, private Syncthing exchange, SMB mounts, rsync sync, par2 verification, and recurring operations | Samba shares, Managed Syncthing, Storage operations |
| Deployments | Single-service deployments and basaltwater.json multi-component manifests |
Deployments, Deployment safety, CI/CD |
| Proxmox | Host discovery, VM/LXC provisioning, lifecycle, resource stats, boot ordering, snapshots, and rolling updates | Proxmox workflows |
| Networking | Static addressing, internal HTTPS site/preview hosting, inventory, and read-only Proxmox firewall planning | Internal web, Networking |
| Sysadmin | SSH, transfers, health, services, logs, upgrades, and reachability | Sysadmin shortcuts |
Setup arguments are saved without passwords, reconstructed commands redact secrets, and workspace credential files use restrictive permissions. Deployments keep persistent application state outside release directories and create verified backups where required. Read Deployment safety for rollback and recovery behavior.
Steps detect the target machine type and skip capabilities that cannot safely run in containers. Kernel, firewall, and desktop behavior is therefore capability-aware rather than assumed. See Machine types.
The security profile hardens SSH, the firewall, package updates, journald, fail2ban, and service boundaries. Samba uses authenticated SMB3+, signing and encryption, TCP 445 only, and validated configuration reloads. See the Samba guide and maintenance guide.
On Debian profiles, automatic APT updates remain enabled, while language ecosystem upgrades and release selection use conservative freshness and opt-in policies. Cleanup uses bounded cache, log, journal, and temporary-artifact policies. On APT hosts other than Proxmox, it purges packages APT marks unused, including superseded kernels; Proxmox uses guarded kernel-only cleanup. It expires recognized crash reports and returns unused filesystem blocks to supported physical, virtual, and Proxmox storage, then checks block and inode pressure across local mounts. See the recurring maintenance guide. CachyOS uses bounded cleanup during setup and keeps system updates under the desktop user's control.
Use patch for general saved-configuration changes. Use a feature-specific
fast path when available—for example, basaltw shares HOST updates Samba
users, access, paths, and share declarations without running unrelated setup
work. See Saved configuration operations.
# Explore the command help and preview a local profile without applying it
basaltw --help
basaltw setup server_dev localhost "$USER" --node --dry-run
# List configurations saved by this account (empty before the first live setup)
basaltw listUse the beginner walkthrough to apply your first setup, the quick reference for saved-host commands, and the documentation index for the feature map.
Run the default checks from a checkout. This includes building a wheel in a temporary directory, installing it into an isolated virtual environment, and smoke-testing all installed launchers outside the source tree:
make checkFor the faster smoke-suite edit loop without the wheel build, use
make check-fast.
Routine continuous integration runs the suite in Debian Trixie on Python 3.13, the interpreter shipped by that release. Version-tagged releases additionally run the suite on the minimum supported Python version (3.10) and the latest Python 3 version in the release policy (3.14). Expensive live tests remain opt-in.
See Saved configuration operations for test selectors and Proxmox workflows for live-host notes.
Apache License 2.0