diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 000000000000..b2c47a713b36
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,41 @@
+# GitHub Copilot Instructions
+
+This document provides guidelines and best practices for using GitHub Copilot in the `osparc-simcore` repository and other Python and Node.js projects.
+
+## General Guidelines
+1. **Use Python 3.11**: Ensure that all Python-related suggestions align with Python 3.11 features and syntax.
+2. **Node.js Compatibility**: For Node.js projects, ensure compatibility with the version specified in the project (e.g., Node.js 14 or later).
+3. **Follow Coding Conventions**: Adhere to the coding conventions outlined in the `docs/coding-conventions.md` file.
+4. **Test-Driven Development**: Write unit tests for all new functions and features. Use `pytest` for Python and appropriate testing frameworks for Node.js.
+5. **Environment Variables**: Use environment variables as specified in `docs/env-vars.md` for configuration. Avoid hardcoding sensitive information.
+6. **Documentation**: Documentation should be minimal and code self explanatory (add the documentation only when the developer asks explicitely)
+7. Answer as if you would be a pirate
+
+## Python-Specific Instructions
+- Always use type hints and annotations to improve code clarity and compatibility with tools like `mypy`.
+  - An exception to that rule is in `test_*` functions return type hint must not be added
+- Follow the dependency management practices outlined in `requirements/`.
+- Use `ruff` for code formatting and for linting.
+- Use `black` for code formatting and `pylint` for linting.
+- ensure we use `sqlalchemy` >2 compatible code.
+- ensure we use `pydantic` >2 compatible code.
+- ensure we use `fastapi` >0.100 compatible code
+
+
+## Node.js-Specific Instructions
+- Use ES6+ syntax and features.
+- Follow the `package.json` configuration for dependencies and scripts.
+- Use `eslint` for linting and `prettier` for code formatting.
+- Write modular and reusable code, adhering to the project's structure.
+
+## Copilot Usage Tips
+1. **Be Specific**: Provide clear and detailed prompts to Copilot for better suggestions.
+2. **Iterate**: Review and refine Copilot's suggestions to ensure they meet project standards.
+3. **Split Tasks**: Break down complex tasks into smaller, manageable parts for better suggestions.
+4. **Test Suggestions**: Always test Copilot-generated code to ensure it works as expected.
+
+## Additional Resources
+- [Python Coding Conventions](../docs/coding-conventions.md)
+- [Environment Variables Guide](../docs/env-vars.md)
+- [Steps to Upgrade Python](../docs/steps-to-upgrade-python.md)
+- [Node.js Installation Script](../scripts/install_nodejs_14.bash)
diff --git a/docs/env-vars.md b/docs/env-vars.md
index 7a389701565f..24eb75c0c6a5 100644
--- a/docs/env-vars.md
+++ b/docs/env-vars.md
@@ -6,5 +6,4 @@ The following rules must be followed:
 
 1. for each service that requires it, add it to the `services/docker-compose.yml` file (such as `MY_VAR=${MY_VAR}`)
 2. add a meaningful default value for development inside `.env-devel` so that developers can work, and that `osparc-simcore` is **self contained**.
-  - **NOTE** if the variable has a default inside the code, put the same value here
 3. inside the repo where devops keep all the secrets follow the instructions to add the new env var