diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
new file mode 100644
index 0000000..524e16a
--- /dev/null
+++ b/.devcontainer/Dockerfile
@@ -0,0 +1,15 @@
+FROM mcr.microsoft.com/devcontainers/python:1-3.12-bookworm
+
+ARG POETRY_VERSION=2.0.1
+
+ENV TZ=Etc/UTC \
+    POETRY_HOME=/opt/poetry \
+    VIRTUAL_ENV=/home/vscode/.venv \
+    POETRY_VIRTUALENVS_CREATE=false
+ENV PATH="${VIRTUAL_ENV}/bin:${POETRY_HOME}/bin:${PATH}"
+
+RUN python -m venv "${POETRY_HOME}" \
+    && "${POETRY_HOME}/bin/python" -m pip install --no-cache-dir \
+        "poetry==${POETRY_VERSION}" \
+    && python -m venv "${VIRTUAL_ENV}" \
+    && chown -R vscode:vscode "${VIRTUAL_ENV}"
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
new file mode 100644
index 0000000..63b70d1
--- /dev/null
+++ b/.devcontainer/devcontainer.json
@@ -0,0 +1,27 @@
+{
+  "name": "cwms-cli",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "args": {
+      "POETRY_VERSION": "2.0.1"
+    }
+  },
+  "remoteUser": "vscode",
+  "containerEnv": {
+    "TZ": "Etc/UTC",
+    "POETRY_HOME": "/opt/poetry",
+    "VIRTUAL_ENV": "/home/vscode/.venv",
+    "POETRY_VIRTUALENVS_CREATE": "false"
+  },
+  "postCreateCommand": "git config --global --add safe.directory \"$(pwd)\" && poetry install --with dev --no-interaction",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python"
+      ],
+      "settings": {
+        "python.defaultInterpreterPath": "/home/vscode/.venv/bin/python"
+      }
+    }
+  }
+}
diff --git a/.github/workflows/cli-tests.yml b/.github/workflows/cli-tests.yml
index 0a09949..e788a4f 100644
--- a/.github/workflows/cli-tests.yml
+++ b/.github/workflows/cli-tests.yml
@@ -38,3 +38,17 @@ jobs:
 
       - name: Run full test suite
         run: poetry run pytest -q
+
+  test-devcontainer:
+    name: Test dev container on 3.12
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Build dev container and run tests
+        uses: devcontainers/ci@v0.3
+        with:
+          push: never
+          runCmd: poetry run pytest -q
diff --git a/AGENTS.md b/AGENTS.md
index 8681762..33f04b9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,7 +1,21 @@
-# AGENTS.md
+# Repository instructions
 
 Guidance for coding agents working in `HydrologicEngineeringCenter/cwms-cli`.
 
+- Never push to `origin` unless the user explicitly says they are ready for
+  that push.
+- Use JDK 21 or newer for new work that is not intended to run on T7 systems.
+  On Windows, use JDK 21 at `C:\Program Files\Java\jdk-21`. On Linux or other
+  Unix-like systems, select an installed JDK 21 or newer through `JAVA_HOME`.
+  Use another Java version only when the target or task requires it.
+- Use the `.devcontainer` Linux/Python 3.12 environment for changes involving
+  time zones, paths, native libraries, HEC-DSS, or other operating-system-
+  dependent behavior.
+- Run the full dev-container test suite with
+  `devcontainer exec --workspace-folder . poetry run pytest -q` when the dev
+  container is available. The standard CI matrix separately covers Python 3.9
+  and Python 3.12 package compatibility.
+
 ## Terminal colors
 
 - Use the shared helpers in `cwmscli.utils.colors` for user-facing terminal
diff --git a/README.md b/README.md
index aa8ccce..93b038f 100644
--- a/README.md
+++ b/README.md
@@ -40,3 +40,21 @@ from cwmscli.usgs.getusgs_cda import getusgs_cda
 from cwmscli.usgs.getusgs_measurements_cda import getusgs_measurements_cda
 from cwmscli.usgs.getUSGS_ratings_cda import getusgs_rating_cda
 ```
+
+## Development environment
+
+The repository includes a Linux/Python 3.12 development container exercised by
+a dedicated CI job. Open the repository with the VS Code Dev Containers
+extension, or use the Dev Container CLI:
+
+```sh
+devcontainer up --workspace-folder .
+devcontainer exec --workspace-folder . poetry run pytest -q
+```
+
+The container installs project dependencies with Poetry and uses
+`/home/vscode/.venv`, so it does not reuse a host operating system's `.venv`.
+Poetry itself is kept in a separate `/opt/poetry` environment. Use the container
+for changes involving time zones, paths, native libraries, or other
+operating-system-dependent behavior. Standard Python 3.9 and Python 3.12
+installations remain covered by the existing CI matrix.