🧰 TSYSDevStack Toolbox Base
Daily-driver development container with curated tooling
Daily-driver development container for ToolboxStack work. It provides a reproducible Ubuntu 24.04 environment with curated shell tooling, package managers, and helper scripts.
🚀 Quick Start
| 📋 Step |
🛠️ Command |
📝 Description |
| 1. 🏗️ Build the image |
./build.sh |
Builds and tags the image as tsysdevstack-toolboxstack-toolbox-base:dev. Uses docker buildx with a local cache at .build-cache/ for faster rebuilds. |
| 2. ▶️ Start the container |
./run.sh up |
Defaults to the release-current tag; override with TOOLBOX_IMAGE_OVERRIDE=... when testing other tags. Mise runtimes persist to your host in ~/.local/share/mise and ~/.cache/mise so language/tool downloads are shared across projects. |
| 3. 🔗 Attach to a shell |
docker exec -it tsysdevstack-toolboxstack-toolbox-base zsh |
or: bash / fish |
| 4. ⏹️ Stop the container |
./run.sh down |
Stops the running container |
💡 Note: The compose service mounts the current repo to /workspace (read/write) and runs as the mapped host user (toolbox).
🏷️ Image Tagging & Releases
| 🛠️ Operation |
📋 Command |
📝 Details |
| 🏗️ Build Development |
./build.sh |
Builds :dev for active development |
| 🚀 Release |
./release.sh <semver> |
Rebuilds, retags, and pushes :dev, :release-current, and v<semver> (e.g., ./release.sh 0.2.0). Requires a clean git tree. |
| 🧪 Dry Run |
./release.sh --dry-run <semver> |
Rehearse the release without pushing (optionally --allow-dirty for experimentation only) |
| 📦 Downstream |
FROM tsysdevstack-toolboxstack-toolbox-base:release-current |
Downstream Dockerfiles should inherit from release-current (or pin to a semantic tag for reproducibility) |
🧩 Tooling Inventory
🐚 Shells & Prompts
| 🛠️ Tool |
📋 Name |
📝 Notes |
| 🐚 |
zsh |
Z shell with oh-my-zsh framework |
| 🐟 |
fish |
Friendly interactive shell |
| 🧑💻 |
bash |
Bourne again shell |
| ⭐ |
starship |
Cross-shell prompt |
| 💎 |
oh-my-zsh |
Zsh framework |
⭐ Starship prompt enabled for all shells; oh-my-zsh configured with git + fzf plugins.
🪄 Runtime & CLI Managers
| 🛠️ Tool |
📋 Name |
📝 Notes |
| 🪄 |
mise |
Runtime manager for languages and tools |
| 💧 |
aqua |
CLI version manager |
mise handles language/tool runtimes (activation wired into zsh/bash/fish); aqua manages standalone CLIs with config at ~/.config/aquaproj-aqua/aqua.yaml.
🧰 Core CLI Utilities
| 🛠️ Tool |
📋 Name |
📝 Notes |
| 📦 |
curl |
Command-line data transfer |
| 📥 |
wget |
Network downloader |
| 🔐 |
ca-certificates |
Common CA certificates |
| 🧭 |
git |
Distributed version control |
| 🔧 |
build-essential |
Essential build tools |
| 🔍 |
ripgrep |
Fast search tool |
| 🧭 |
fzf |
Fuzzy finder |
| 📁 |
fd |
Simple, fast & user-friendly alternative to find |
| 📖 |
bat |
Cat clone with syntax highlighting |
| 🔗 |
openssh-client |
OpenSSH client applications |
| 🧵 |
tmux |
Terminal multiplexer |
| 🖥️ |
screen |
Terminal multiplexer |
| 📈 |
htop |
Interactive process viewer |
| 📉 |
btop |
A monitor of resources |
| ♻️ |
entr |
Run arbitrary commands when files change |
| 📊 |
jq |
Command-line JSON processor |
| 🌐 |
httpie |
User-friendly curl replacement |
| ☕ |
tea |
Package manager for dev projects |
| 🧮 |
bc |
Arbitrary precision calculator language |
Provides ergonomic defaults plus toolchain deps for compiling runtimes (no global language installs).
🌊 Aqua-Managed CLIs
| 🛠️ Tool |
📋 Name |
| 🐙 |
gh (GitHub CLI) |
| 🌀 |
lazygit |
| 🪄 |
direnv |
| 🎨 |
git-delta |
| 🧭 |
zoxide |
| 🧰 |
just |
| 🧾 |
yq |
| ⚡ |
xh |
| 🌍 |
curlie |
| 🏠 |
chezmoi |
| 🛠️ |
shfmt |
| ✅ |
shellcheck |
| 🐳 |
hadolint |
| 🐍 |
uv |
| 🔁 |
watchexec |
Extend via ~/.config/aquaproj-aqua/aqua.yaml. These packages are baked into the image at build time for consistency and reproducibility. Direnv logging is muted and hooks for direnv/zoxide are pre-configured for zsh, bash, and fish.
🤖 AI CLI Tools
| 🛠️ Tool |
📋 Name |
| 🧠 |
@just-every/code |
| 🤖 |
@qwen-code/qwen-code |
| 💎 |
@google/gemini-cli |
| 🔮 |
@openai/codex |
| 🌐 |
opencode-ai |
AI-powered command-line tools for enhanced development workflows. Node.js is installed via mise to support npm package installation.
🐳 Container Workflow
| 🛠️ Feature |
📋 Description |
| 🐳 |
Docker socket mount (/var/run/docker.sock) - Enables Docker CLIs inside the container; host Docker daemon required. |
🧠 AI Tool Configuration
| 🛠️ Feature |
📋 Description |
| 🧠 |
Host directories for AI tools - Host directories for AI tool configuration and cache are mounted to maintain persistent settings and data across container runs. |
👤 Runtime Environment
| 🛠️ Feature |
📋 Description |
| 👤 |
Non-root user toolbox (UID/GID mapped) |
| 🗂️ |
/workspace mount - Maintains host permissions and isolates artifacts under artifacts/ToolboxStack/toolbox-base |
🛠️ Extending the Sandbox
| 🧩 Task |
🛠️ Command |
📝 Description |
| 🧮 Add a runtime |
mise use python@3.12 |
(per project). Run inside /workspace to persist .mise.toml. |
| 🧰 Add a CLI tool |
Update ~/.config/aquaproj-aqua/aqua.yaml, then run aqua install |
Extend the available tools in the environment |
| 🛠️ Adjust base image |
Modify Dockerfile, run ./build.sh, and keep this README & PROMPT in sync |
Make changes to the base environment |
🔁 Documentation policy: Whenever you add/remove tooling or change the developer experience, update both this README and the PROMPT file so the next collaborator has an accurate snapshot.
📂 Project Layout
| 📁 Path |
📝 Purpose |
Dockerfile |
Defines the toolbox-base image. |
docker-compose.yml |
Compose service providing the container runtime. |
build.sh |
Wrapper around docker build with host UID/GID mapping. |
run.sh |
Helper to bring the compose service up/down (exports UID/GID env vars). |
.devcontainer/devcontainer.json |
VS Code remote container definition. |
aqua.yaml |
Default aqua configuration (gh, tea, lazygit). |
PROMPT |
LLM onboarding prompt for future contributors (must remain current). |
✅ Verification Checklist
After any image changes:
- 🏗️ Build Test: Run
./build.sh and ensure it succeeds.
- 🧪 Functionality Test: Optionally
./run.sh up and sanity-check key tooling (e.g., mise --version, gh --version).
- 📝 Documentation Sync: Update this README and the
PROMPT with any new or removed tooling.
🤝 Collaboration Notes
| 📋 Best Practice |
📝 Description |
| 👤 Non-Root Policy |
Container always runs as the mapped non-root user; avoid adding steps that require root login. |
| 🧩 Tooling Consistency |
Prefer mise/aqua for new tooling to keep installations reproducible. |
| 📚 Documentation Sync |
Keep documentation synchronized (README + PROMPT) so future contributors can resume quickly. |
📄 License
See LICENSE for full terms.
ReachableCEO
3ec443eef8