Skip to main content

Container Quick Start

The SubZeroDev Workspace container includes PowerShell, the setup scripts, and the statically built documentation. The only host prerequisite is Docker.

Serve the Documentation​

docker run --rm --name subzerodev-workspace-docs \
  -p 8080:8080 \
  ghcr.io/the-running-dev/subzerodev-workspace:latest

Open http://localhost:8080. The default docs command runs nginx in the foreground and serves the documentation embedded at image-build time.

Run the Setup​

Use the setup command to pass arguments to setup-llm/scripts/setup.ps1 inside the Linux container:

docker run --rm -it \
  ghcr.io/the-running-dev/subzerodev-workspace:latest \
  setup -Client Codex -SkipGitHub

This removes the host PowerShell requirement, but setup remains container-scoped. It installs and registers tools inside that container. Persist configuration and working files with named volumes or bind mounts:

docker volume create subzerodev-workspace-config

docker run --rm -it \
  -v subzerodev-workspace-config:/root/.config \
  -v "$PWD:/workspace" \
  ghcr.io/the-running-dev/subzerodev-workspace:latest \
  setup -Client Codex -SkipGitHub

Enable Docker-Based Integrations​

GitHub MCP launches another container, so it requires access to the host Docker engine. Mount the Docker socket and the git-ignored token file when you deliberately want that access:

docker run --rm -it \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$PWD/setup-llm/docker/.env:/opt/workspace/setup-llm/docker/.env:ro" \
  -v subzerodev-workspace-config:/root/.config \
  ghcr.io/the-running-dev/subzerodev-workspace:latest \
  setup -Client Codex

Mounting the Docker socket gives the container control of the host Docker daemon. Only run trusted images and scripts with this mount. Docker Desktop users may need to enable Docker-socket sharing for Linux containers.

Open PowerShell​

The image uses PowerShell as its Docker entry point. Start an interactive shell with:

docker run --rm -it ghcr.io/the-running-dev/subzerodev-workspace:latest pwsh

The scripts are available under /opt/workspace/setup-llm, and /workspace is reserved for mounted projects.

Build Locally​

Initialize the documentation submodule before building:

git submodule update --init --recursive
docker build -f setup-llm/Dockerfile -t subzerodev-workspace .
docker run --rm -p 8080:8080 subzerodev-workspace

Pull requests build the Dockerfile and upload an OCI image archive as a workflow artifact. Builds from main additionally publish ghcr.io/the-running-dev/subzerodev-workspace:latest and an immutable commit-SHA tag to GitHub Container Registry.