diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
new file mode 100644
index 00000000..6ef17f99
--- /dev/null
+++ b/.devcontainer/devcontainer.json
@@ -0,0 +1,37 @@
+{
+  "name": "pytm devcontainer",
+  "image": "mcr.microsoft.com/devcontainers/base:ubuntu24.04",
+  "features": {
+      "ghcr.io/devcontainers/features/common-utils:2": {
+          "installZsh": "false",
+          "configureZshAsDefaultShell": "false",
+          "installOhMyZsh": "false",
+          "installOhMyZshConfig": "false",
+          "upgradePackages": "true",
+		  "nonFreePackages": "false"
+      },
+      "ghcr.io/devcontainers/features/git:1": {
+          "version": "latest",
+          "ppa": "true"
+      },
+      "ghcr.io/devcontainers-extra/features/eza:1": {},
+      "ghcr.io/devcontainers-extra/features/fd:1": {},
+      "ghcr.io/devcontainers-extra/features/fzf:1": {},
+      "ghcr.io/devcontainers-extra/features/ripgrep:1": {},
+      "ghcr.io/devcontainers-extra/features/uv:1": {},
+      "ghcr.io/devcontainers/features/python:1": {
+          "version": "3.13",
+          "installTools": "false",
+          "optimize": "false",
+          "enableShared": "false",
+          "installPath": "/usr/local/python",
+          "installJupyterlab": "false"
+      },
+      "ghcr.io/meaningful-ooo/devcontainer-features/homebrew:2": {
+          "shallowClone": "false"
+      },
+      "ghcr.io/devcontainers-extra/features/pandoc:1": {}
+  },
+  "postCreateCommand": "brew install graphviz plantuml",
+  "remoteUser": "vscode"
+}
diff --git a/DEVCONTAINER.md b/DEVCONTAINER.md
new file mode 100644
index 00000000..8dc7b12c
--- /dev/null
+++ b/DEVCONTAINER.md
@@ -0,0 +1,32 @@
+# Devcontainer
+
+The `pytm` devcontainer is an adaption of the
+[devcontainer Ubuntu base image](https://github.com/devcontainers/images/tree/main/src/base-ubuntu)
+for painless CLI management support via [`brew`](https://brew.sh/).
+This enables easy integration into devcontainer based workflows, CLI based instalaltion of additional `brew` packages
+as well as common devcontainer features which are based on `apt` packages in a lot of cases.
+
+The devcontainer uses the following [features](https://containers.dev/features):
+
+- [common-utils](https://github.com/devcontainers/features/tree/main/src/common-utils)
+- [git](https://github.com/devcontainers/features/tree/main/src/git)
+- [homebrew](https://github.com/meaningful-ooo/devcontainer-features/tree/main/src/homebrew)
+- some modern tools from [devcontainer-extra/features](https://github.com/devcontainers-extra/features)
+
+## Build a local devcontainer via the CLI
+
+To manage devcontainer via the CLI you can use
+[devcontainer cli](https://github.com/devcontainers/cli).
+
+    devcontainer build --workspace-folder .
+
+The first startup takes some time for building the image. Later startups are significantly faster.
+
+## Usage
+
+The most simple, getting started usage scenario is:
+
+    vscode ➜ /workspaces/pytm (devcontainer) $ mkdir -p tm
+    vscode ➜ /workspaces/pytm (devcontainer) $ ./tm.py --report docs/basic_template.md | pandoc -f markdown -t html > tm/report.html
+    vscode ➜ /workspaces/pytm (devcontainer) $ ./tm.py --dfd | dot -Tpng -o tm/dfd.png
+    vscode ➜ /workspaces/pytm (devcontainer) $ ./tm.py --seq | java -Djava.awt.headless=true -jar $PLANTUML_PATH -tpng -pipe > tm/seq.png