itpplasma · krystophny · Sep 19, 2026 · May 28, 2026 · May 28, 2026 · May 28, 2026
diff --git a/.devcontainer/postCreateCommand.sh b/.devcontainer/postCreateCommand.sh
@@ -1,9 +1,12 @@
 #!/bin/bash
 
 CODE_TEMPLATE=/usr/local/src/code_template
-CODE=/workspaces/code
+INFRA=/workspaces/code
+CODE=/workspaces
 
-ln -s $CODE_TEMPLATE/.venv $CODE/.venv
+# .venv is infra-private; external and libneo are workspace-shared
+ln -s $CODE_TEMPLATE/.venv $INFRA/.venv
+mkdir -p $CODE/external
 ln -s $CODE_TEMPLATE/external/fgsl-1.6.0 $CODE/external/fgsl-1.6.0
 cp -r $CODE_TEMPLATE/libneo $CODE/libneo
 

diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
diff --git a/.github/workflows/setup.yml b/.github/workflows/setup.yml
@@ -76,17 +76,27 @@ jobs:
             libmetis-dev \
             libboost-all-dev
 
+      # TODO(infra-relocation): this workflow runs on version tags only and is
+      # NOT exercised by PR CI. After the infra relocation, setup.sh builds the
+      # shared deps into $CODE/external (the workspace, parent of this checkout),
+      # so the steps below must build there and bundle external/ into the release
+      # tarball alongside the infra content. Validate on a real tag before
+      # cutting the next release; main.yml still consumes the pinned old release.
       - name: Setup
         run: |
           set -e
           source scripts/setup.sh
-          pushd external
-            ../scripts/setup/mfem.sh
+          CODE="$(cd .. && pwd)"
+          pushd "$CODE/external"
+            "$GITHUB_WORKSPACE/scripts/setup/mfem.sh"
           popd
 
       - name: Build tarball
         run: |
           set -e
+          CODE="$(cd .. && pwd)"
+          # flat release archive: infra content + the shared external/ at root
+          cp -r "$CODE/external" ./external
           tar -czf /tmp/code.tar.gz .
 
       - name: Create GitHub Release

diff --git a/.gitignore b/.gitignore
@@ -36,3 +36,4 @@ tests/**/*.h5
 .coverage
 mars_coords2stor_thetageom.profile
 .vscode/launch.json
+._*
diff --git a/README.md b/README.md
@@ -5,7 +5,8 @@ to setup development and use of internal and external codes. Our development
 environment is Visual Studio Code, and we strongly recommend GitHub Copilot
 there and in the [CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli/setting-up-github-copilot-in-the-cli).
 
-CODE is based around our standard Debian bookworm system at ITPcp and provides
+CODE supports the standard Debian system at ITPcp and Ubuntu LTS development
+VMs, and provides
 
 - Setup scripts `scripts/setup/...`
 - Quality-of-life shell commands via `scripts/util.sh`
@@ -14,16 +15,39 @@ CODE is based around our standard Debian bookworm system at ITPcp and provides
 - Container definitions
 - VSCode settings
 
+## Layout
+
+This repository is the `infra` directory of a workspace. The workspace is the
+environment variable `$CODE`; this repository is `$INFRA`, equal to
+`$CODE/infra`. The code checkouts sit in the workspace next to `infra`:
+
+    $CODE/
+      infra/      this repository (activation, setup scripts, modules, .venv)
+      external/   prebuilt third-party libs, shared by all codes
+      libneo/     code checkout
+      SIMPLE/     code checkout
+      ...
+
+Activation exports both. `$INFRA` holds the infra-private paths (`scripts`,
+`.venv`, `modules`). `$CODE` is the workspace root, so the codes resolve their
+dependencies as `$CODE/<name>` and read prebuilt libraries from
+`$CODE/external`.
+
 ## Getting Started
 
-If you haven't done so earlier, set up your SSH keys in `~/.ssh` via `ssh-keygen`
-with a **blank passphrase** and add the content of `id_rsa.pub` to Gitlab and GitHub
-for authentication.
+Authenticate GitHub and GitLab with their normal CLIs, or create a protected SSH
+key and add its public key to the service. Do not put credentials into this
+repository or a cloud-init file.
 
 ### Perparing your machine
 
 On Linux: At ITPcp computers all packages should be installed to get going.
-On your own Debian system, run [scripts/setup/debian.sh](scripts/setup/debian.sh).
+On your own Debian or Ubuntu system, install the complete scientific workstation
+with:
+
+    sudo scripts/setup/apt.sh full
+
+The old `scripts/setup/debian.sh` command remains a compatibility wrapper.
 
 On Mac: The recommended way via **orbstack**
 and **devpod** as described in [scripts/setup/mac.sh](scripts/setup/mac.sh).
@@ -35,30 +59,31 @@ to install Debian Linux via WSL2. Then follow the Linux instructions.
 
 ### Initial setup
 
-Clone the repository to your working copy, at the institute this is
+Clone this repository into an `infra` directory inside your workspace. At the
+institute the workspace is `/proj/plasma/CODE/<username>`:
 
-    git clone git@github.com:itpplasma/code /proj/plasma/CODE/<username>
+    git clone git@github.com:itpplasma/code /proj/plasma/CODE/<username>/infra
 
-Then open the directory in VS Code with
+Open the workspace in VS Code with
 
-    code code
+    code /proj/plasma/CODE/<username>
 
 When asked to initialize the devcontainer, remove the message.
 Run the setup script manually with
 
-    scripts/setup.sh
+    infra/scripts/setup.sh
 
-The setup will install external dependencies and create
-a Python virtual environment in the hidden `.venv` directory.
+The setup installs external dependencies and creates the Python virtual
+environment in `infra/.venv`.
 
 Finally, activate the environment with
 
-    source activate.sh
+    source infra/activate.sh
 
 To use this environment as a standard, put the activation
 script into bashrc with
 
-    echo "source $PWD/activate.sh" >> ~/.bashrc
+    echo "source /proj/plasma/CODE/<username>/infra/activate.sh" >> ~/.bashrc
 
 ## External codes
 
@@ -103,3 +128,65 @@ Integration tests are run by
     pytest tests/
 
 This will perform all the tests in `tests/` and its subfolders.
+
+## Incus AI sandbox
+
+A single long-lived, unprivileged Debian trixie container for running coding
+agents against your real working directories:
+
+    scripts/setup/incus-ai-sandbox.sh      # provision once
+    ln -s $PWD/scripts/ai-sandbox.sh ~/bin/ai
+    cd ~/code/some-project
+    ai                                     # shell, in this directory
+
+`~/code` and `~/proj` are always attached at their real absolute paths, so all
+code and project checkouts remain visible even when you start `ai` from inside
+one of them. A directory outside those roots is attached at the same absolute
+path for that session and detached again when the last session in it exits.
+Several directories can be attached concurrently. The container reaches the
+internet but not the LAN, the host, or any unattached host path, and starts with
+no software installed beyond the stock image. Details, network policy, and the
+boundary this does and does not provide: [`docs/ai-sandbox.md`](docs/ai-sandbox.md).
+
+## Multipass AI coding VM
+
+The Multipass profile creates the same headless Ubuntu LTS environment on ARM64
+and x86-64 hosts. It defaults to 8 CPUs, 16 GB RAM, and a 128 GB disk:
+
+    scripts/multipass-ai.sh
+
+Override resources with flags or `MULTIPASS_AI_*` environment variables:
+
+    scripts/multipass-ai.sh --name ai-work --cpus 12 --memory 24G
+
+The launcher deliberately does not use the special instance name `primary` and
+does not mount any host directory. Code starts in `~/workspace`; mount or copy
+only explicitly approved paths later. The small
+[`cloud-init/multipass-ai.yaml`](cloud-init/multipass-ai.yaml) file delegates to
+the same `scripts/setup/apt.sh ai` installer that can be run directly on Debian
+or Ubuntu, avoiding a second package definition.
+
+Codex, Claude Code, OpenCode, Pi, uv, chezmoi, GitHub/GitLab CLIs, compilers,
+scientific libraries, and the common CachyOS-derived CLI tools are installed.
+Normal CLI logins and provider tokens persist inside the VM, but no credential
+is baked into cloud-init or Git. To install/update private Helpy and Sloptools
+after GitHub login:
+
+    gh auth login
+    ai-private-tools
+
+That script installs the two stdio MCP servers and constrains Sloptools' project
+root to `~/workspace`. Re-run `ai-update` for public AI CLIs and
+`ai-private-tools` for the private MCP tools.
+
+Personal settings stay separate from this generic public repository. After Git
+authentication, an optional private chezmoi repository (including age-encrypted
+files) can be applied and later updated with:
+
+    ai-user-config git@github.com:YOUR-ORG/YOUR-DOTFILES.git
+    ai-user-config
+
+API keys that cannot use a CLI login may be kept in
+`~/.config/ai-infra/env` with mode `0600`; an example is created alongside it.
+This file remains local to the VM unless the user deliberately manages an
+encrypted version with chezmoi.
diff --git a/SIMPLE b/SIMPLE