🟧📦 squarebox

Modern CLI/TUI tools and AI coding assistants in a portable development Box.

Run the same terminal environment on your desktop, server, or Codespace. One-line install, interactive setup, and persistent tools and settings.

Install

Requires Docker or Podman, plus Git (Git for Windows). The installer detects your runtime and asks which to use if both are installed. Need Docker?

Linux / macOS / Git Bash

curl -fsSL https://github.com/SquareWaveSystems/squarebox/releases/latest/download/install.sh | bash

Windows (PowerShell 7+)

irm https://github.com/SquareWaveSystems/squarebox/releases/latest/download/install.ps1 | iex

The installer pulls the latest stable Release and sets up ~/squarebox. First login runs a wizard for Git identity, GitHub sign-in, and optional tools. Keep using the same adapter (Bash/Git Bash or PowerShell) for updates and uninstall.

For edge builds, custom paths, scripted setup, or Windows flags, see the usage reference. Upgrading? Check the migration guides and changelog.

Start

squarebox        # or: sqrbx

Your code lives in ~/squarebox/workspace, mounted at /workspace. Shell history, credentials, assistant data, and SDKs live in the persistent squarebox-home volume. Both survive Box replacement. Selected system packages are reinstalled automatically; manually installed system packages are lost.

For a persistent server or NAS, see server deployment. For VS Code or GitHub Codespaces, see Dev Containers and Codespaces.

What's included

CLI Tools

Name	Description
bat	Cat clone with syntax highlighting
bubblewrap	Unprivileged sandboxing tool (bwrap), used by the Codex CLI sandbox
curl	URL data transfer
delta	Syntax-highlighting pager for git diffs
difftastic	Syntax-aware structural diff tool (difft)
eza	Modern ls replacement
fd	Fast, user-friendly find alternative
fzf	Fuzzy finder
gh	GitHub CLI
glow	Terminal markdown renderer
gum	Tool for shell scripts and dotfiles
jq	JSON processor
just	Command runner / modern make alternative
mise	Polyglot tool-version and SDK manager
nano	Default text editor
ripgrep	Fast recursive grep
starship	Cross-shell prompt
xh	Friendly HTTP client
yq	YAML/JSON/XML processor
zoxide	Smarter cd command

What's optional

Choose any combination during first-run setup. Your selections are saved and reused on rebuilds; change them anytime with sqrbx-setup.

AI Coding Assistants

Name	Description
Claude Code	AI coding assistant
GitHub Copilot CLI	Supported GitHub Copilot terminal client (copilot) *
Google Gemini CLI	Google Gemini in the terminal *
OpenAI Codex CLI	OpenAI Codex in the terminal *
opencode	AI coding TUI
Pi Coding Agent	Minimal terminal coding harness (Earendil) *
Oh My Pi	Batteries-included coding harness (omp), installed via mise

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

Text Editors

Nano is always available and remains the fallback default unless you choose an installed editor instead.

Name	Description
micro	Modern, intuitive terminal editor
edit	Terminal text editor (Microsoft)
fresh	Modern terminal text editor
helix	Modal editor (Kakoune-inspired)
nvim	Neovim

Selecting nvim offers a LazyVim starter config. Existing Neovim configuration is preserved. See editor configuration.

TUI Tools

Name	Description
lazygit	Git terminal UI
gh-dash	GitHub dashboard for the terminal
yazi	Terminal file manager
elio	Terminal file manager with rich previews, inline images, and trash support

Terminal Multiplexers

Name	Description
tmux	Classic terminal multiplexer
zellij	Friendly terminal workspace
herdr	Agent multiplexer — run multiple coding agents from one terminal

Shells and SDKs

Bash is the default shell; choose Zsh, Fish, or PowerShell during setup. Node.js, Python, Go, .NET, and Rust are available through mise. See shell configuration and SDK configuration.

Everyday commands

Run these inside the Box:

sqrbx-help               # commands and navigation shortcuts
sqrbx-setup              # rerun the setup wizard
sqrbx-setup ai editors   # reconfigure specific sections
sqrbx-setup --list       # show your selections
sqrbx-update             # check for tool updates
sqrbx-update --apply     # update installed registered tools
sqrbx-update lazygit     # update or install one named tool

From the host, run sqrbx-rebuild to update the Box itself. This keeps your workspace and persistent home, and reuses your installation settings. Some bundled tools require a rebuild to update.

See the aliases, keyboard shortcuts, and update details.

Uninstall

From the host:

sqrbx-uninstall

This removes the Box and shell integration, keeping your workspace and persistent home. sqrbx-uninstall --purge (PowerShell: -Purge) also removes the persistent home and install directory, including a workspace inside it. A custom external workspace is preserved. See uninstall options and recovery.

Security

The Box is a development environment with access to your mounted files and credentials. SSH-directory mounts require explicit opt-in. See SECURITY.md for SSH access, the trust model, artifact verification, and vulnerability reporting.

Make it your own

Fork it, swap tools, or add your own dotfiles. The Dockerfile and tool registry define what's included.