diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
new file mode 100644
index 0000000..15b4505
--- /dev/null
+++ b/.devcontainer/Dockerfile
@@ -0,0 +1,67 @@
+FROM python:3-slim
+
+ARG USERNAME=dev
+ARG UID=1000
+ARG GID=1000
+ARG VERSION="circup"
+
+# Create the user
+RUN groupadd --gid $GID $USERNAME \
+    && useradd --uid $UID --gid $GID -m $USERNAME \
+    #
+    # [Optional] Add sudo support. Omit if you don't need to install software after connecting.
+    && apt-get update \
+    && apt-get install -y sudo \
+    && echo $USERNAME ALL=\(root\) NOPASSWD:ALL > /etc/sudoers.d/$USERNAME \
+    && chmod 0440 /etc/sudoers.d/$USERNAME
+
+# dialout group
+RUN usermod -a -G dialout $USERNAME
+
+# install packages
+RUN apt-get install -y \
+    locales \
+    tree \
+    git \
+    iputils-ping
+
+# cleanup
+RUN rm -rf /var/lib/apt/lists/*
+
+# set locale
+RUN export LC_ALL=en_US.UTF-8
+RUN export LANG=en_US.UTF-8
+RUN locale-gen en_US.UTF-8
+
+RUN pip install --upgrade pip
+
+
+USER ${USERNAME}
+RUN echo 'export PS1="🐍  \[\033[1;36m\]'"${VERSION}"' \[\e[33m\]\W\[\e[m\] \[\033[1;36m\]# \[\033[0m\]"' >> ~/.bashrc
+
+# add local bin to path
+RUN echo "export PATH=\$PATH:/home/${USERNAME}/.local/bin" >> ~/.bashrc
+ENV PATH="${PATH}:/home/${USERNAME}/.local/bin"
+
+WORKDIR /home/${USERNAME}
+
+
+# setup folders for saving vscode extensions
+# https://code.visualstudio.com/remote/advancedcontainers/avoid-extension-reinstalls
+RUN mkdir -p /home/$USERNAME/.vscode-server/extensions \
+    && chown -R $USERNAME \
+    /home/$USERNAME/.vscode-server
+
+
+# install requirements
+COPY requirements.txt requirements.txt
+RUN pip3 install -r requirements.txt && rm requirements.txt
+
+
+# build timestamp
+USER root
+RUN echo ${VERSION} >> /build_date.txt && \
+    date >> /build_date.txt
+
+USER ${USERNAME}
+WORKDIR /home/${USERNAME}
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
new file mode 100644
index 0000000..1317db9
--- /dev/null
+++ b/.devcontainer/devcontainer.json
@@ -0,0 +1,25 @@
+{
+  "initializeCommand": ".devcontainer/prepare_host.sh", // executed on HOST system
+  "image": "local/circup-dev",
+
+  "mounts": [
+    "source=/var/tmp/container-extensions,target=/home/dev/.vscode-server/extensions,type=bind,consistency=cached"
+  ],
+
+
+  // Configure tool-specific properties.
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python",
+        "ms-python.vscode-pylance",
+        "shardulm94.trailing-spaces",
+        "njpwerner.autodocstring",
+        "mhutchie.git-graph",
+        "doi.fileheadercomment",
+        "donjayamanne.githistory",
+        "charliermarsh.ruff"
+      ]
+    }
+  }
+}
diff --git a/.devcontainer/prepare_host.sh b/.devcontainer/prepare_host.sh
new file mode 100755
index 0000000..f71d1da
--- /dev/null
+++ b/.devcontainer/prepare_host.sh
@@ -0,0 +1,20 @@
+#!/bin/bash
+
+# this script prepares the host for the devcontainer.
+
+
+# it is easier to use this script to pre-build the image, instead of using
+# `build` directive in `devcontainer.json`. Less chance of errors ducing container start.
+
+IMG_NAME="local/circup-dev"
+# Get the directory of the script
+SCRIPT_DIR=$(dirname "$0")
+
+# create a directory for the container extensions to avoid reinstallation
+# on container rebuild. Mounted inside devcontainer.
+mkdir -p /var/tmp/container-extensions
+
+
+# buld image
+echo "Building image $IMG_NAME"
+docker build -t $IMG_NAME --build-arg UID=$(id -u) --build-arg GID=$(id -g) -f $SCRIPT_DIR/Dockerfile $SCRIPT_DIR
diff --git a/.devcontainer/requirements.txt b/.devcontainer/requirements.txt
new file mode 100644
index 0000000..738f2c2
--- /dev/null
+++ b/.devcontainer/requirements.txt
@@ -0,0 +1,13 @@
+bump2version
+coverage
+invoke
+ipython
+mypy
+pre-commit
+pytest
+pytest-asyncio
+pytest-cov
+pytest-coverage
+pytest-faulthandler
+pytest-random-order
+ruff