runtime: add workspace runtime (#228)

## Summary

- split the challenge runtime Nix package into `runtime/platform`
- add a `runtime/workspace` build env with a Go workspace entrypoint,
supervisor, and uid 1000 agent
- add dynamic workspace services for tty, desktop, and code, proxied
over Unix sockets
- package `pwnshop` as a proper Python application in the Nix store and
remove the root wrapper

## Validation

- `tools/git-hooks/pre-commit`
- `nix fmt -- --fail-on-change`
- `nix shell nixpkgs#go nixpkgs#gcc --command go test ./...` in
`runtime/workspace/agent`
- `python -m py_compile tools/pwnshop/src/pwnshop/commands/run.py
tools/pwnshop/src/pwnshop/lib/__init__.py`
- Nix builds for `runtime/platform`, `runtime/workspace`, and
`tools/pwnshop`
- packaged `pwnshop --help` and `pwnshop list challenges/program-misuse`

Author: ConnorNelson

.github/actions/determine-modified-challenges/action.yml

@@ -48,12 +48,12 @@ runs:
 
     - name: List modified challenges
       id: list-challenges
-      shell: 'nix shell nixpkgs#uv nixpkgs#git --command bash --noprofile --norc -euo pipefail {0}'
+      shell: 'nix shell .#pwnshop --command bash --noprofile --norc -euo pipefail {0}'
       env:
         MODIFIED_SINCE: ${{ steps.resolve-ref.outputs.ref }}
       run: |
         challenges_file="$RUNNER_TEMP/modified-challenges.txt"
-        ./pwnshop list ./challenges --modified-since="$MODIFIED_SINCE" > "$challenges_file"
+        pwnshop list ./challenges --modified-since="$MODIFIED_SINCE" > "$challenges_file"
         echo "challenges_file=$challenges_file" >> "$GITHUB_OUTPUT"
 
     - uses: actions/github-script@v8

.github/actions/setup-nix/action.yml

@@ -3,7 +3,7 @@ description: Install Nix and configure binary caches for this repo.
 runs:
   using: composite
   steps:
-    - uses: DeterminateSystems/determinate-nix-action@v3.17.1
+    - uses: DeterminateSystems/determinate-nix-action@v3.21.1
       with:
         summarize: false
         extra-conf: |

AGENTS.md

@@ -77,7 +77,7 @@ per archetype (templated web/service, interpreted checker, compiled SUID binary,
 
 ### Dev Environment (Nix)
 
-`nix develop` is required for `pwnshop`. Always enter the dev shell before invoking `pwnshop` (or `./pwnshop`) -- if anything fails unexpectedly, your first check should be whether you are inside the dev shell.
+`nix develop` is required for `pwnshop`. Always enter the dev shell before invoking `pwnshop` -- if anything fails unexpectedly, your first check should be whether you are inside the dev shell.
 
 ```bash
 nix develop

README.md

@@ -32,21 +32,21 @@ git crypt unlock
 
 # Challenge CLI
 
-All developer workflows now run through the `./pwnshop` command. The legacy `./build` helper has been removed, so every rendered, build, run, or test action should use the new CLI instead.
+All developer workflows now run through the `pwnshop` command provided by `nix develop`. The legacy `./build` helper and root `./pwnshop` wrapper have been removed, so every rendered, build, run, or test action should use the packaged CLI instead.
 
 The CLI is implemented with Click and Rich (`tools/pwnshop/src/pwnshop/commands/*.py`) on top of the core helper library in `tools/pwnshop/src/pwnshop/lib/__init__.py`. Keeping formatting/terminal logic in the commands and reusable challenge logic in `tools/pwnshop/src/pwnshop/lib` makes it easy to add or modify commands without duplicating functionality.
 
 All CLI subcommands accept either a direct filesystem path or a challenge slug. Slugs must include the module (e.g., `web-security/path-traversal-1`); the tool searches under `./challenges` for that module/challenge pair and errors if nothing matches.
 
 Primary entry points:
 
-- `./pwnshop list` — enumerate challenges, optionally filtered via `--modified-since`.
-- `./pwnshop render` — materialize a challenge directory or individual template (`--output` defaults to stdout and Rich labels each file when multiple outputs are rendered).
-- `./pwnshop build` — render and build a challenge, returning the Docker image ID.
-- `./pwnshop test` — render, build, and run all `test*/test_*` files inside the challenge.
-- `./pwnshop run` — render, build, and drop into an interactive shell inside the challenge container (use `--user=<uid>` to control the interactive user, default `1000`, `--volume <path>` to mount host paths read-only, or append a command after the challenge to run it instead of `/bin/bash`).
+- `pwnshop list` — enumerate challenges, optionally filtered via `--modified-since`.
+- `pwnshop render` — materialize a challenge directory or individual template (`--output` defaults to stdout and Rich labels each file when multiple outputs are rendered).
+- `pwnshop build` — render and build a challenge, returning the Docker image ID.
+- `pwnshop test` — render, build, and run all `test*/test_*` files inside the challenge.
+- `pwnshop run` — render, build, and drop into an interactive shell inside the challenge container (use `--user=<uid>` to control the interactive user, default `1000`, `--volume <path>` to mount host paths read-only, or append a command after the challenge to run it instead of `/bin/bash`).
 
-Any future automation that renders, builds, runs, or tests challenges should shell out to `./pwnshop ...` rather than reimplementing those pieces of the workflow.
+Any future automation that renders, builds, runs, or tests challenges should shell out to `pwnshop ...` rather than reimplementing those pieces of the workflow.
 
 The standalone `discord-feedback` helper is available in `nix develop` for Discord-derived curriculum feedback automation.
 
@@ -122,7 +122,7 @@ nix develop
 More details: `docs/development.md`.
 
 If you are not using Nix, you will need a working Docker setup and the Python tooling for `pwnshop`.
-At minimum, install `uv` and then use `./pwnshop ...` (it will manage Python deps from `tools/pwnshop/uv.lock`).
+At minimum, install the Python dependencies for `tools/pwnshop` or run it with `uv run --project tools/pwnshop --with-editable tools/pwnshop pwnshop ...`.
 
 For legacy/manual environments, you can still install a basic set of Python packages in a virtual environment:
 
@@ -134,19 +134,19 @@ pip install black click jinja2 pyastyle pwntools rich
 
 ```bash
 # run the full test suite for a challenge
-./pwnshop test web-security/path-traversal-1
+pwnshop test web-security/path-traversal-1
 
 # build the Docker image without testing
-./pwnshop build web-security/path-traversal-1
+pwnshop build web-security/path-traversal-1
 
 # render the challenge into a directory for inspection
-./pwnshop render web-security/path-traversal-1 --output /tmp/output
+pwnshop render web-security/path-traversal-1 --output /tmp/output
 
 # render a single template file to stdout (or write to a file)
-./pwnshop render web-security/path-traversal-1/tests_public/test_normal.py.j2 --output /tmp/output-file
+pwnshop render web-security/path-traversal-1/tests_public/test_normal.py.j2 --output /tmp/output-file
 
 # list challenges, optionally filtered by git history
-./pwnshop list --modified-since origin/main
+pwnshop list --modified-since origin/main
 ```
 
 ## Important Notes / Common Gotchas
@@ -181,7 +181,7 @@ The process of porting is:
 6. If using templates, use `{% extends %}` and `{% block setup %}` for customization
 7. Ensure all executable files are marked as such: `chmod +x ./$MODULE_ID/$CHALLENGE_ID/**/*.j2`. Rendered files inherit permissions from the template.
 8. Port verification logic to `./$MODULE_ID/$CHALLENGE_ID/tests_public` (functionality) and `./$MODULE_ID/$CHALLENGE_ID/tests_private` (exploitation)
-9. Test thoroughly: `./pwnshop test $MODULE_ID/$CHALLENGE_ID`
+9. Test thoroughly: `pwnshop test $MODULE_ID/$CHALLENGE_ID`
 10. Once testcases pass, double-check the template (both rendered and at rest) against the legacy challenge to ensure that the challenge has been ported without any functionality change.
 
 # Adding a new key

challenges/linux-luminarium/destruction/rm-rf-root-read/challenge/check

@@ -3,10 +3,16 @@
 import time
 import os
 
+def entry_count(path):
+    try:
+        return len(os.listdir(path))
+    except FileNotFoundError:
+        return 0
+
 flag = open("/flag").read()
 
 while True:
-    if len(os.listdir("/")) > 10 or len(os.listdir("/usr")) > 3 or len(os.listdir("/etc")) > 5 or os.path.exists("/flag"):
+    if entry_count("/") > 10 or entry_count("/usr") > 3 or entry_count("/etc") > 5 or os.path.exists("/flag"):
         print("Looks like you haven't wiped the system! We'll check again in 5 seconds...")
     else:
         print("YES! You did it again! Go read the flag!")

challenges/linux-luminarium/destruction/rm-rf-root-search/challenge/check

@@ -3,10 +3,16 @@
 import time
 import os
 
+def entry_count(path):
+    try:
+        return len(os.listdir(path))
+    except FileNotFoundError:
+        return 0
+
 flag = open("/flag").read()
 
 while True:
-    if len(os.listdir("/")) > 10 or len(os.listdir("/usr")) > 3 or len(os.listdir("/etc")) > 5 or os.path.exists("/flag"):
+    if entry_count("/") > 10 or entry_count("/usr") > 3 or entry_count("/etc") > 5 or os.path.exists("/flag"):
         print("Looks like you haven't wiped the system! We'll check again in 5 seconds...")
     else:
         print("YES! You did it again! Go read the flag!")

challenges/linux-luminarium/destruction/rm-rf-root/challenge/check

@@ -3,10 +3,16 @@
 import time
 import os
 
+def entry_count(path):
+    try:
+        return len(os.listdir(path))
+    except FileNotFoundError:
+        return 0
+
 flag = open("/flag").read()
 
 while True:
-    if len(os.listdir("/")) > 10 or len(os.listdir("/usr")) > 3 or len(os.listdir("/etc")) > 5 or os.path.exists("/flag"):
+    if entry_count("/") > 10 or entry_count("/usr") > 3 or entry_count("/etc") > 5 or os.path.exists("/flag"):
         print("Looks like you haven't wiped the system! We'll check again in 5 seconds...")
     else:
         print("YES! You wiped it, you wild hacker! The flag is yours:")

docs/development.md

@@ -30,8 +30,8 @@ On shell entry, the dev shell will start the challenge runtime (using sudo). Thi
 Then use `pwnshop` for all workflows:
 
 ```bash
-./pwnshop list
-./pwnshop test web-security/path-traversal-1
+pwnshop list
+pwnshop test web-security/path-traversal-1
 ```
 
 ## Community Dojo Workflow
@@ -66,15 +66,15 @@ Shared Dockerfiles and packages reuse Docker's layer cache, so the monorepo does
 - Check unit status/logs:
 
 ```bash
-systemctl status pwn-challenge-runtime.service
-journalctl -u pwn-challenge-runtime.service -b --no-pager
+systemctl status pwn-platform-runtime-docker.service
+journalctl -u pwn-platform-runtime-docker.service -b --no-pager
 ```
 
 ## Non-Nix Setup (Not Recommended)
 
 You can run `pwnshop` without Nix, but you must supply:
 
-- `uv` (the `./pwnshop` wrapper uses `uv run`)
+- Python dependencies for `tools/pwnshop` (or use `uv run --project tools/pwnshop --with-editable tools/pwnshop pwnshop ...`)
 - a working Docker environment (daemon + client)
 
 Private tests/solutions are encrypted with `git-crypt`; you will need access to the relevant module key(s) to unlock them.

flake.lock

@@ -9,11 +9,14 @@
   };
 
   inputs = {
-    nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11";
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05";
   };
 
   outputs =
-    { self, nixpkgs }:
+    {
+      self,
+      nixpkgs,
+    }:
     let
       lib = nixpkgs.lib;
       systems = [ "x86_64-linux" ];
@@ -39,55 +42,57 @@
         }
       );
 
-      devShells = forAllSystems (
+      packages = forAllSystems (
         system:
         let
           pkgs = import nixpkgs { inherit system; };
 
-          pwn-challenge-runtime = import ./runtime { inherit pkgs lib; };
+          pwn-workspace-runtime = import ./runtime/workspace { inherit pkgs; };
+          pwn-platform-runtime = import ./runtime/platform { inherit pkgs lib; };
 
-          pwnshop = pkgs.writeShellApplication {
-            name = "pwnshop";
-            runtimeInputs = with pkgs; [
-              git
-              uv
-            ];
-            text = ''
-              set -euo pipefail
-              root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
-              exec "$root/pwnshop" "$@"
-            '';
-          };
+          pwnshop = import ./tools/pwnshop { inherit pkgs pwn-workspace-runtime; };
+          discord-feedback = import ./tools/feedback { inherit pkgs; };
+        in
+        {
+          default = pwnshop;
+          inherit
+            discord-feedback
+            pwn-platform-runtime
+            pwn-workspace-runtime
+            pwnshop
+            ;
+        }
+      );
 
-          discord-feedback = pkgs.writeShellApplication {
-            name = "discord-feedback";
-            runtimeInputs = with pkgs; [
-              git
-              uv
-            ];
-            text = ''
-              set -euo pipefail
-              root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
-              exec "$root/tools/feedback/discord-feedback" "$@"
-            '';
-          };
+      devShells = forAllSystems (
+        system:
+        let
+          pkgs = import nixpkgs { inherit system; };
+
+          pwn-workspace-runtime = import ./runtime/workspace { inherit pkgs; };
+          pwn-platform-runtime = import ./runtime/platform { inherit pkgs lib; };
+
+          pwnshop = import ./tools/pwnshop { inherit pkgs pwn-workspace-runtime; };
+          discord-feedback = import ./tools/feedback { inherit pkgs; };
         in
         {
           default = pkgs.mkShell {
             packages = with pkgs; [
               asciinema
-              clang-tools
+              discord-feedback
               docker
               git
               git-crypt
               jq
-              discord-feedback
-              pwn-challenge-runtime
+              pwn-platform-runtime
+              pwn-workspace-runtime
               pwnshop
               tomlq
               uv
             ];
             shellHook = ''
+              export PWN_WORKSPACE="${pwn-workspace-runtime}"
+
               # Install the secret-test encryption pre-commit hook (idempotent,
               # non-destructive). Resolve the path Git actually runs the hook from
               # -- honoring core.hooksPath and the shared hooks dir of a linked
@@ -107,14 +112,21 @@
                 fi
               fi
 
-              if [ "$(id -u)" -eq 0 ]; then
-                export DOCKER_HOST="$(${lib.getExe pwn-challenge-runtime})"
-              elif command -v sudo >/dev/null 2>&1; then
-                export DOCKER_HOST="$(sudo ${lib.getExe pwn-challenge-runtime})"
-              else
-                echo "error: cannot start the challenge runtime without root privileges" >&2
+              sudo=
+              if [ "$(id -u)" -ne 0 ]; then
+                if command -v sudo >/dev/null 2>&1; then
+                  sudo=sudo
+                else
+                  echo "error: cannot start the challenge runtime without root privileges" >&2
+                  return 1
+                fi
+              fi
+
+              if ! runtime_environment="$($sudo ${lib.getExe pwn-platform-runtime})"; then
+                echo "error: failed to start the challenge runtime" >&2
                 return 1
               fi
+              eval "$runtime_environment"
             '';
           };
         }