Brokk Sandbox

Brokk Sandbox is a Docker-based development environment for working with Brokk and general-purpose software projects. It packages the Brokk CLI together with common build, scripting, networking, version-control, and container tools in a reproducible image.

The image is based on ghcr.io/brokkai/build-platform-image:v0.1.0 and runs as the non-root brokk user. It is intended to provide a ready-to-use workspace rather than a project-specific application runtime.

Included tools

The image includes, among other utilities:

• Brokk CLI
• GCC, G++, Make, CMake, Autotools, and pkg-config
• Git and Git LFS
• Python 3, pip, pipx, uv, Ruff, Black, and Pytest
• OpenJDK 25
• Docker CLI
• curl, wget, jq, yq, archive tools, and common shell utilities

Build the image

Build the image from the repository root:

docker build -t brokk-sandbox .

Run the sandbox

Mount a local project into /workspace and start an interactive shell:

docker run --rm -it \
  -v "$PWD:/workspace" \
  brokk-sandbox \
  bash

The container defaults to running brokk, so you can also start the CLI directly:

docker run --rm -it \
  -v "$PWD:/workspace" \
  brokk-sandbox

If the Brokk workflow needs to interact with the host Docker daemon, expose the Docker socket when starting the container:

docker run --rm -it \
  -v "$PWD:/workspace" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  brokk-sandbox \
  bash

Only expose the Docker socket when it is required. Access to the socket grants broad control over the host Docker daemon.

Configuration

Brokk configuration files are ignored by default through .gitignore, while the following project-level files remain trackable:

• .brokk/style.md
• .brokk/review.md
• .brokk/project.properties

Place these files in the mounted project directory when you want to customize Brokk for a project.

Publishing

The GitHub Actions workflow in .github/workflows/docker-publish.yml builds and publishes the image to GitHub Container Registry whenever a version tag matching v* is pushed. For example:

git tag v0.1.2
git push origin v0.1.2

The resulting image is published under:

ghcr.io/<owner>/<repository>:<version>

License

This project is licensed under the GNU General Public License v3.0. See LICENSE for the full license text.