TSYSDevStack/ToolboxStack/output/toolbox-template/README.md

🧰 TSYSDevStack Toolbox Template

Template for creating new toolboxes that extend from the toolbox-base image.

---

🚀 Quick Start

1. Create a new toolbox

   cp -r /path/to/toolbox-template /path/to/new-toolbox
   cd /path/to/new-toolbox
   

2. Customize the toolbox

   • Edit Dockerfile to add toolbox-specific tooling
   • Modify docker-compose.yml to adjust service configuration
   • Update SEED to define the toolbox's purpose and goals

3. Build the toolbox

   ./build.sh
   

4. Start the toolbox

   ./run.sh up
   

5. Access the toolbox

   docker exec -it tsysdevstack-toolboxstack-<toolbox-name> zsh
   

6. Stop the toolbox

   ./run.sh down
   

---

🧱 Architecture

• Base Image: Extends from tsysdevstack-toolboxstack-toolbox-base:release-current
• User: Runs as non-root toolbox user (UID/GID mapped to host)
• Workspace: Mounts current directory to /workspace (read/write)
• Runtime: Inherits all tooling from base plus toolbox-specific additions

---

🛠️ Customization

Dockerfile

Extend the base image with toolbox-specific tooling:

# Extend from the toolbox-base image
FROM tsysdevstack-toolboxstack-toolbox-base:release-current

# Add toolbox-specific packages or configurations
RUN apt-get update && apt-get install -y --no-install-recommends \
    specific-package \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

docker-compose.yml

Adjust service configuration for toolbox-specific needs:

services:
  my-toolbox:
    # Inherits all base configuration
    # Add toolbox-specific volumes, ports, etc.
    volumes:
      - ./custom-config:/home/toolbox/.config/custom-tool

SEED

Define the toolbox's purpose and goals:

- Describe what this toolbox should provide (languages, CLIs, workflows)
- List required base image modifications or additional mounts
- Note verification or testing expectations specific to this toolbox

---

📂 Project Layout

Path	Purpose
Dockerfile	Extends base image with toolbox-specific tooling
docker-compose.yml	Service configuration for the toolbox
build.sh	Wrapper around docker build with host UID/GID mapping
run.sh	Helper to bring the service up/down
.devcontainer/devcontainer.json	VS Code remote container definition
SEED	Defines the toolbox's purpose and goals
PROMPT	LLM onboarding prompt for future contributors

---

🤝 Collaboration Notes

• Inherits all collaboration policies from toolbox-base
• Document toolbox-specific additions in README.md and PROMPT
• Update SEED only when the high-level objectives change
• Prefer aqua/mise for new tooling to keep installations reproducible
• Keep documentation synchronized for future contributors