🟧📦 squarebox

A curated set of modern CLI/TUI tools and AI coding assistants in a container. Batteries included.

For developers who live in the terminal but need to work across
multiple platforms and devices.

squarebox packages a complete terminal-based development environment
into a single container (Docker or Podman): modern CLI tools, AI coding
assistants, language SDKs, and an opinionated set of shell aliases. Run the
same box anywhere (desktop, VPS, or Codespace) and SSH in from your laptop,
tablet, or phone (please don't).

The goal is to make modern terminal tooling easy and accessible. One-line
install, interactive first-run setup, sensible defaults (thanks omarchy).

(Actual setup may involve more staring at the screen.)

Prerequisites

• Docker or Podman (see one-line install below if you don't have either)
• Git - on Windows, install Git for Windows

The installer auto-detects which runtime is available. If both are installed, it
asks which to use. Override with SQUAREBOX_RUNTIME=docker or
SQUAREBOX_RUNTIME=podman.

Don't have Docker or Podman? One-line install

macOS (via Homebrew):

brew install --cask docker-desktop

Linux (official convenience script - inspect it first at get.docker.com):

curl -fsSL https://get.docker.com | sh && sudo usermod -aG docker $USER

Log out and back in (or run newgrp docker) so your shell picks up the new group.

Windows (via winget, in PowerShell 7+):

winget install --id Docker.DockerDesktop -e

On macOS and Windows, start Docker Desktop once after install so the daemon is
running before you continue.

Install

These commands clone the repo, build the container image, and drop you into the
container (if possible). On first login, a setup script runs automatically to
configure git (pulling your name and email from the host's global git config
if available), optionally sign in to GitHub CLI, your choice of AI coding
assistant, and language SDKs.

Stable

curl -fsSL https://raw.githubusercontent.com/SquareWaveSystems/squarebox/main/install.sh | bash

Edge

curl -fsSL https://raw.githubusercontent.com/SquareWaveSystems/squarebox/main/install.sh | bash -s -- --edge

Stable installs the latest tagged release (pre-release tags like -rc are skipped). Edge uses the latest commit on main.

If the install fails or you want to see the full docker build and git output, re-run with --verbose:

curl -fsSL https://raw.githubusercontent.com/SquareWaveSystems/squarebox/main/install.sh | bash -s -- --verbose

Windows (PowerShell 7+)

Windows users can install directly from PowerShell - no Git Bash required.
This handles clone, build, container creation, and PowerShell aliases
(sqrbx, squarebox, etc.) natively:

irm https://raw.githubusercontent.com/SquareWaveSystems/squarebox/main/install.ps1 | iex

Once installed, you can re-run or pass flags from the local copy:

.\install.ps1              # re-install / update
.\install.ps1 -Edge        # latest main instead of latest release
.\install.ps1 -Verbose     # show full build output

Note: irm ... | iex does not support flags - PowerShell interprets them
as arguments to Invoke-Expression, not the script. Use the local
.\install.ps1 form for -Edge or -Verbose.

Start

squarebox        # or: sqrbx

These are shell functions wrapping docker start -ai squarebox (or
podman start -ai squarebox), added automatically for Bash, Zsh, and
PowerShell 7+.

The container is persistent: it suspends on exit and resumes on start, keeping
installed packages, config, and shell history intact between sessions. Your
code and tool config live on the host under ~/squarebox (workspace/ for
code, .config/ for tool config) via volume mounts, so they survive even if
the container is deleted.

What's included

CLI Tools

What's optional

Selected during first-run setup. Choose any combination, all, or none.
Selections are saved to the workspace volume and reused automatically on
container rebuilds.

AI Coding Assistants

* Requires Node.js (auto-installed if needed).

Text Editors

Nano is always available as the default editor.

TUI Tools

Installed during first-run setup. Choose any combination:

Terminal Multiplexers

Installed during first-run setup. Choose either, both, or neither:

SDKs

Aliases

Multiplexer Keybindings (Experimental)

Both tmux and zellij ship with Omarchy-inspired defaults and matching keybindings:

Update

Quick update (from inside the container)

sqrbx-update

Checks all GitHub-released tools against latest versions and updates them
in-place. No rebuild required. Your container state, SDKs, and config are
preserved.

sqrbx-update              # show available updates (dry run)
sqrbx-update --apply      # download and install all updates
sqrbx-update lazygit      # update a single tool
sqrbx-update --list       # list all tools and current versions

Full rebuild (from the host)

sqrbx-rebuild

Pulls the latest changes, rebuilds the image, and replaces the container.
Your code in ~/squarebox/workspace is safe since it lives on the host.
Setup selections (AI tool, editors, SDKs, GitHub auth) are persisted in the
workspace volume and restored automatically. However, shell history, manually
installed packages, and custom config files inside the container are lost.

What survives a rebuild

To preserve extra files across rebuilds, store them in /workspace/.squarebox/.

Tip: Use sqrbx-update from inside the container to update tools without
rebuilding. Only use sqrbx-rebuild when the base image itself needs to
change (new apt packages, new base tools, Dockerfile changes).

Disk usage

The base image (CLI tools only, no optional components) is ~370 MB on disk.

First-run selections add to that:

A typical setup (Claude Code + Node.js + one editor) lands around ~800 MB.
Sizes are approximate and will vary as tools are updated.

Security

Base image tools are pinned to specific versions and verified against SHA256
checksums when the Docker image is built, so docker build is reproducible.

Optional tools selected during first-run setup (editors, TUIs, OpenCode, nvm,
Go, zellij) install the latest upstream release at the time you run setup. The
trust model is the same as running each tool's installer yourself: HTTPS
downloads from the project's official GitHub release (or upstream server). You
get new features without waiting for a squarebox release, at the cost of
build-time pinning for that tier.

Third-party install scripts (Claude Code, uv, .NET) delegate to the vendor
installer. npm-based AI tools (Copilot CLI, Gemini CLI, Codex CLI) use npm's
built-in integrity verification.

For the full trust model (what install.sh does on your machine, how each
layer is verified, and how to inspect the script before running it) see
SECURITY.md.

Devcontainer / Codespaces

Open this repo in VS Code with the
Dev Containers extension,
or launch it in GitHub Codespaces.
The included .devcontainer/devcontainer.json builds the full squarebox image
automatically.

The interactive first-run setup is skipped in devcontainer mode. To configure
AI tools or SDKs, run ~/setup.sh from the integrated terminal.

You can also attach to a running codespace directly from your local terminal
using gh codespace ssh.

Uninstall

docker stop squarebox 2>/dev/null; docker rm squarebox
docker rmi squarebox
rm -rf ~/squarebox

Then remove the sqrbx and sqrbx-rebuild aliases from your shell config
(~/.bashrc, ~/.zshrc, or ~/Documents/PowerShell/Microsoft.PowerShell_profile.ps1).
Back up ~/squarebox/workspace first if you need your code.

Make it your own

squarebox is meant to be a starting point, not a finished product. Fork it,
swap out tools, add your own dotfiles, change the theme - build the dev
environment that fits the way you work. The Dockerfile is intentionally
straightforward and the tool registry (scripts/lib/tools.yaml) makes it easy
to add or remove tools. Use it as a base, take what's useful, and make it yours.