# ๐Ÿงฐ 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 ` | Rebuilds, retags, and pushes `:dev`, `:release-current`, and `v` (e.g., `./release.sh 0.2.0`). Requires a clean git tree. | | ๐Ÿงช Dry Run | `./release.sh --dry-run ` | 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: 1. ๐Ÿ—๏ธ **Build Test**: Run `./build.sh` and ensure it succeeds. 2. ๐Ÿงช **Functionality Test**: Optionally `./run.sh up` and sanity-check key tooling (e.g., `mise --version`, `gh --version`). 3. ๐Ÿ“ **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](../../LICENSE) for full terms.