Vivant dans le Nord de la France, le défi pour moi est double : un ensoleillement plus faible que dans le sud, et un chauffage hivernal (via pompe à chaleur) très énergivore.

Dans cet article, je partage les résultats d'une analyse de 1,5 an de production et je détaille la simulation réalisée en intégrant les données réelles de ma dernière facture EDF OA : le manque à gagner sur la revente.

Le paysage énergétique en 2026 : Le poids du contrat

Les tarifs de revente ont beaucoup évolué. Pour mon installation, les conditions sont excellentes, ce qui change paradoxalement la rentabilité d'une batterie :

• Coût d'achat (Réseau) : ~0,208 €/kWh (HP) / ~0,164 €/kWh (HC)

• Tarif de Revente (Mon contrat) : 13,01 c€/kWh (jusqu'à un plafond de 9 600 kWh/an).

• Tarif de Revente (Nouveaux contrats 2026) : 4,00 c€/kWh.

Le calcul de rentabilité repose sur l'économie nette : si je stocke 1 kWh pour ne pas l'acheter 0,20 €, mais que j'aurais pu le vendre 0,13 €, mon gain réel n'est que de 0,07 €.

Pourquoi les moyennes journalières sont trompeuses

Beaucoup de simulateurs en ligne utilisent des "moyennes quotidiennes". C'est une erreur. Pour comprendre le ROI d'une batterie, il faut des données horaires. Une moyenne peut indiquer que vous avez produit 15 kWh et consommé 15 kWh, mais si la production est à midi et la consommation à minuit, sans batterie, vous achetez 100 % de votre énergie nocturne.

Mon profil de consommation (Données réelles)

Pour comprendre l'intérêt d'une batterie, il faut d'abord isoler la consommation "talon" de la maison des gros postes de dépense énergétique. Dans mon cas, deux éléments dominent : la Pompe à Chaleur (PAC) en hiver et la recharge du Véhicule Électrique (VE).

L'analyse de mes données sur une année complète révèle une disparité saisonnière massive, exacerbée par le chauffage :

L'impact du Véhicule Électrique (VE)

C'est ici que les moyennes deviennent piégeuses. Sur l'année, j'ai effectué 132 sessions de recharge, consommant un total de 2 454 kWh. Une recharge typique peut monter jusqu'à 60 kWh en une seule nuit.

Si l'on inclut ces recharges dans la moyenne nocturne, on obtient un chiffre de 17,1 kWh/nuit. Mais en réalité :

• 70% des nuits (sans recharge VE), ma consommation est modérée.
• 30% des nuits, la consommation explose pour charger la voiture.

Ce point est crucial : charger une voiture électrique la nuit se fait déjà au tarif Heures Creuses (0,1637 €). Utiliser une batterie pour charger un VE reviendrait à stocker de l'électricité (avec 10% de perte) pour l'utiliser au même tarif... une opération financièrement nulle.

Le constat global reste sans appel : dans le Nord, l'hiver est une opération blanche. Ma pompe à chaleur consomme tout. Par contre, en été, l'excédent est massif. Sur ma dernière facture, j'ai injecté 2 431 kWh sur le réseau, générant 316,27 € de revenus (hors prime).

Analyse du ROI : L'impact du tarif de revente

Voici la simulation comparative entre mon contrat actuel et un contrat signé aujourd'hui.

Scénario A : Mon contrat (Revente à 13,01 c€/kWh)

Ici, chaque kWh stocké est un kWh "perdu" pour la revente à un prix élevé.

Verdict : Avec un tarif de revente aussi élevé (13,01 c€), la batterie n'est absolument pas rentable financièrement. Elle mettrait 20 ans à s'amortir, soit bien au-delà de sa durée de vie probable.

Scénario B : Nouvelle installation 2026 (Revente à 4,00 c€/kWh)

Pour un nouvel acquéreur, la faible rémunération du surplus change la donne.

Verdict : Pour un nouveau contrat, la batterie de 10-15 kWh devient rentable en 9 à 10 ans, ce qui correspond à la durée de garantie des constructeurs.

Focus Technique : Comment j'ai validé ces chiffres

J'ai construit un pipeline d'analyse pour "rejouer" les 1,5 dernières années en simulant l'ajout d'une batterie.

1. Stockage long terme : J'utilise VictoriaMetrics pour stocker les données de mon ECU APSystems et de mon Linky.

2. Extraction : Un script Python (collect_data.py) récupère les données par "chunks" de 31 jours pour éviter les timeouts.

3. Simulation : Le script battery_simulator.py calcule l'état de charge (SoC) heure par heure, en appliquant une efficacité de 90%.

# Extrait de la logique de simulation
for hour in data:
    net_power = production - consommation
    if net_power > 0:
        # On charge la batterie avec l'excédent (perte de revente à 13.01c)
        current_soc += min(net_power, capacity - current_soc) * 0.90
    else:
        # On décharge pour éviter l'achat réseau à 20.8c
        current_soc -= min(abs(net_power), current_soc)

Conclusion : Faut-il sauter le pas ?

L'analyse est sans appel :

1. Si vous avez un ancien contrat (type 13 c€/kWh) : Financièrement, ne le faites pas. Vendre votre surplus est plus rentable que de l'utiliser via une batterie coûteuse.

2. Si vous démarrez aujourd'hui (4 c€/kWh) : La batterie est indispensable pour maximiser votre investissement.

3. L'aspect Prime : N'oubliez pas que l'autoconsommation avec vente de surplus donne droit à une prime (dans mon cas 1 380 €), ce qui aide à financer l'installation initiale, mais ne change pas la logique de cycle de la batterie.

Le choix de la batterie en 2026 est donc devenu une question de contrat autant que de technologie.

Retrouvez les scripts et les données sur mon GitHub : ha-energy-analysis.

To test this, I decided to dedicate a full day to really digging into the BMAD method (which stands for Breakthrough Method for Agile AI-Driven Development). If you aren't familiar with it, BMAD is an open-source framework that basically applies Agile discipline to AI coding. Instead of just treating the AI as a single, chaotic autocomplete tool, BMAD forces you to interact with specialized AI "personas" (like an Analyst, Product Manager, and Architect). It makes you generate strict, version-controlled artifacts, like a PRD and technical architecture, before any actual code is written.

I’d used it a few times before and found it a bit long, but this time, I gave it the time it deserved. The goal? Take a raw idea through every phase of software design using these AI agents, right up to the point of coding. Here is how it went, and more importantly, what it taught me about the future of our jobs.

The Journey from Idea to MVP

Using the BMAD method, I took my test idea through five distinct phases:

• 1. Market Search: Let’s be honest, most of our "genius" ideas have already been built by someone else! The Analyst agent guides you through a complete market analysis, pulling in data and results. It acts as an early reality check to see if the project is actually worth pursuing.

• 2. The Analyst (Building the PRD): This is where you build the Product Requirements Document, and it’s where I spent a lot of time. The method drives you down different paths, asking relentless questions and adapting to your answers. It was fascinating because my idea actually grew stronger throughout the process. Step by step, the AI helped me bolt on new features to improve the core product.

• 3. Epics and Stories: Once the PRD is locked, the Product Manager agent steps in to define the epics and user stories for the MVP. The agent continues to guide and ask questions, but you have full control to adapt its proposals.

• 4. The Tech Architect: Here is where rubber meets the road. You move from functional/non-functional requirements to technical ones. The Architect agent proposes stacks and architecture directions based on SLA requirements. You then drive it toward your preferred solution: identifying components, frameworks, specific versions, and deployment strategies.

• 5. The UX: Since my application had a frontend, I entered the design phase. The agent generated Markdown files describing page styles and even spit out sample HTML pages to visualize the result.

At this point, you ask the agent for a "readiness check." It reviews everything, fixes a few lingering issues, and boom: step one of your project is done.

Breaking the "AI Aesthetic" with Stitch

There’s a frustrating reality in vibe coding: if you don’t give the AI highly specific prompts, it will default to the exact same theme style. All AI-generated apps start to look suspiciously similar.

To fix this, I spent some time using a different tool for the UX. Since I have a Google AI subscription, I jumped into Stitch. It was honestly quite impressive.

I took the Markdown files generated in the previous step (describing the project and pages) and asked the LLM to draw the different pages. Stitch acts almost like an AI-empowered Figma. You can manually tweak text, positions, and images, or just ask the AI to modify them for you.

A Quick Tooling Tip: For this entire discovery and design process, I strictly used gemini-cli (also part of my subscription). Because it uses a different quota, it allowed me to save all my tokens in antigravity purely for the heavy lifting of the actual development phase.

Once the design is done, the next steps are standard: feed the product info and architecture into the developer agents, ask them to generate highly-detailed, "AI-implementable" tech stories, and let the agents code and test them.

So... Are Developers Being Replaced?

Going through this process made me think deeply about the current state of the "Developer."

Right now, anyone with a solid idea and enough domain knowledge to challenge an AI can do almost all of the first part of this process... except for the technical architecture. When the AI proposes architecture, it asks technical questions to move forward. It asks for guidance on deployment, performance bottlenecks, data flows, and language choices. This is where technical skills are still absolutely required. Recent industry data heavily supports this shift. According to late-2025/early-2026 reports from firms like Gartner and DX:

• Code generation is mainstream, but it's not the whole job: ~93% of developers now use AI coding assistants. Furthermore, around 27% of all production code is now entirely AI-authored.

• The "10x Developer" myth is dead: While AI speeds up raw coding tasks by about 26% (saving devs ~3.6 hours a week), the overall organizational delivery speed has only improved by about 8-10%. Why? Because the bottleneck simply shifted from writing code to reviewing and architecting systems.

• The 70% Problem: AI gets you 70% of the way there incredibly fast. But bridging that final 30%—fixing edge cases, ensuring security, and tying complex microservices together—requires deep human expertise. In fact, unmonitored AI code has been shown to introduce 1.7x more defects.

I don't necessarily want to call someone who doesn't type code a "Developer" anymore. Maybe we are all evolving into "Software Engineers" in the truest sense of the word. Or perhaps we need a completely new job title: Agent Supervisor? (Gartner actually predicts that by 2028, the developer's role will officially shift from implementation to orchestration—so we are already there!).

The Junior and PM Dilemmas

This evolution brings up two massive questions for the industry:

1. What about Juniors? How does someone who doesn't yet know architecture become an "expert" Agent Supervisor? Recent studies have shown a worrying trend: developers who use AI just to generate code for them (without understanding it) score significantly lower on comprehension tests. If they aren't grinding out the code, how do they learn? The answer is the same as it has always been: reading, breaking things, and mentorship. People must work together and share experiences. AI doesn't replace the senior-junior mentorship dynamic; it makes it more critical than ever.

2. What about Non-Technical Roles? This is the harder pill to swallow. If a technical "Agent Supervisor" can use AI to do all the discovery, market research, and PRD analysis (like I did in a single day), where does that leave traditional Product Managers? Why shouldn't technical people just own the product readiness phase and then immediately move on to the coding agents?

The landscape is shifting rapidly. Typing the code itself is becoming the easy part. The real value is now in the vision, the architecture, and the ability to confidently supervise the machine that builds it.

I decided to reverse-engineer it and build a complete Home Assistant integration from scratch. Not by spending weeks manually reading JavaScript and mapping HTTP calls, but by using AI as my primary tool. Here's how I did it — and how you can apply the same approach to any undocumented web service.

Step 1: Inspecting the Web Application

The first thing I did was open the CSNet Manager website and fire up the browser's DevTools. The Network tab is your best friend when reverse-engineering any web application.

After logging in, the dashboard shows a clean interface with your heating zones — in my case, two zones ("Bibliothèque" and "Salon") with their target and current temperatures:

But the real gold is in what happens behind the scenes. Filtering by XHR/Fetch requests in the Network tab, I quickly found that the web app calls several REST endpoints, all returning JSON:

Navigating directly to /data/elements, I could see the raw JSON response:

💡 Tip: If you're reverse-engineering a web service, start with the Network tab. If the API returns JSON (and not some proprietary binary format), you're in luck — the backporting work will be much simpler.

This was the first "good news": the API is straightforward HTTP calls with JSON responses. No WebSockets, no GraphQL, no obfuscated binary protocol. Just good old REST.

Step 2: Understanding the Data — The Hard Part

Here's a sample of what the /data/elements response looks like (redacted):

{
  "status": "success",
  "data": {
    "name": "Maison de Marco",
    "weatherTemperature": 11,
    "elements": [
      {
        "deviceName": "Hitachi PAC",
        "parentName": "Salon",
        "elementType": 1,
        "mode": 1,
        "realMode": 1,
        "onOff": 1,
        "operationStatus": 5,
        "settingTemperature": 18.5,
        "currentTemperature": 23.0,
        "ecocomfort": 1,
        "alarmCode": 0,
        "c1Demand": false,
        "c2Demand": true,
        "silentMode": -1,
        "fanSpeed": -1,
        "doingBoost": false,
        "yutaki": true
      }
    ]
  }
}

The field names are somewhat descriptive, but what do the values mean? What is elementType: 1 vs elementType: 5? What's operationStatus: 5? What does ecocomfort: 1 map to?

And here's the real challenge: I only have one device with one specific configuration — two water circuits, no water heater, no swimming pool, no fan coils. To make this integration useful for everyone, I needed to support configurations I don't have. How do you understand data you've never seen?

Step 3: Reading the JavaScript Source — Bingo

The answer was staring at me from the browser's Sources tab. The JavaScript files powering the CSNet Manager web app contain all the logic to interpret the API data. And fortunately, they're not heavily obfuscated.

In a file like csnet.js, I found exactly what I needed:

Operation status codes:

// From the CSNet Manager JavaScript source
var OPST_OFF = 0;
var OPST_COOL_D_OFF = 1;
var OPST_COOL_T_OFF = 2;
var OPST_COOL_T_ON = 3;
var OPST_HEAT_D_OFF = 4;
var OPST_HEAT_T_OFF = 5;  // ← My "Salon" has this value!
var OPST_HEAT_T_ON = 6;
var OPST_DHW_OFF = 7;
var OPST_DHW_ON = 8;
var OPST_SWP_OFF = 9;
var OPST_SWP_ON = 10;
var OPST_ALARM = 11;

Temperature limit validation:

function validateValue(v, def) {
    if (v != null && v != undefined && v != 0 && v != -1)
        return v;
    return def;
}

Element type mapping:

• elementType 1 = C1 Air circuit (standard heat pump, 8-35°C range)

• elementType 2 = C2 Air circuit

• elementType 3 = DHW (Domestic Hot Water)

• elementType 4 = SWP (Swimming Pool)

• elementType 5 = C1 Water circuit (Yutaki/Hydro, 20-80°C range)

• elementType 6 = C2 Water circuit

Alarm origin maps, fan speed constants, OTC (Outdoor Temperature Compensation) types — everything was there, clearly written in JavaScript, waiting to be translated into Python.

💡 Key insight: When a web service has no API documentation, the JavaScript source code is the documentation. The browser needs to understand the data to display it, so the code is effectively a reference implementation.

Step 4: Bringing in the AI

Now came the fun part. Instead of manually reading through thousands of lines of JavaScript and mapping every constant, every condition, every edge case into Python — I fed everything to an AI.

The Architect: Claude Opus

I used Claude Opus (available in tools like Antigravity and GitHub Copilot) as my architect. Here's what I asked it to do:

1. Analyse the JavaScript source files — understand the data model, the constants, the business logic

2. Cross-reference with the JSON API responses — map every field to its meaning

3. Design the Home Assistant integration architecture — entities, sensors, coordinators, config flows

4. Create detailed GitHub issues — each one a user story with acceptance criteria, technical notes, and implementation details

The AI produced a structured breakdown organized into milestones:

Each issue looked something like:

[Enhancement] Add Silent/Quiet Mode Support (#64)

What: Add silent mode control based on the silentMode field from the elements API

Technical notes: The JavaScript uses silentMode: 0 for off and silentMode: 1 for on. The value -1 means the feature is not available for this device.

Acceptance criteria:

• Switch entity that toggles silent mode

• Entity is only created when silentMode ≠ -1

• Toggle sends POST to /data/indoor/heat_setting with silentMode parameter

You can see all these issues on the GitHub issues page.

Step 5: The AI-Driven Development Workflow

With the architecture defined and the issues created, I entered the implementation phase. Here's the workflow I used consistently throughout the project:

The Architect + Coder Model

Why two models? Using a highly capable model (Claude Opus) for architecture and a faster/cheaper model (Claude Sonnet, GitHub Copilot) for implementation keeps costs reasonable while maintaining quality. The architect model produces detailed enough specifications that a less powerful model can implement them accurately.

For each issue:

1. The coding AI creates a feature branch

2. It implements the code following the issue specifications

3. It writes unit tests

4. It creates a PR with a description of all changes

5. I review the code, test on my real Hitachi heat pump, and merge

You can see the entire history of this process in the pull requests — each PR is a single feature or bug fix, with a clear description of what was implemented and why.

Step 6: Community-Driven Refinement — The Secret Weapon

Here's where the project truly came alive. Building the initial integration was one thing — making it work for everyone was another.

Remember my earlier challenge? I only have one device configuration (two air circuits, no water heater, no pool). How do you support hardware you don't own?

The answer: the community.

Within weeks of releasing the first version on HACS, 4-5 users with different Hitachi configurations started regularly testing and reporting feedback. Each new tester was like finding a puzzle piece I couldn't buy:

• 🔥 One user had a DHW (Domestic Hot Water) heater → We discovered elementType: 3 and the settingTempDHW field, then built the water heater entity

• 🏊 Another had a swimming pool heater → We found elementType: 4 with its 24-33°C temperature range

• 🌡️ A user with a Yutaki S2 + Yutampo waterboiler → Confirmed the integration works with water circuits (elementType: 5 and 6)

• 💨 Someone with fan coils reported a different speed mapping → We added legacy vs standard fan speed models

• 📊 Users asked for more sensors — compressor stats, outdoor temperatures, pump speeds → We surfaced more data from the installationdevices endpoint

Each time someone reported "I have this configuration and here's my elements JSON", I knew we could expand support. The JSON response from /data/elements became our common debugging language — any user could capture it from their browser and share it (redacting private data) to help identify unmapped fields.

The real "aha moment": Every time someone said "I have this specific setup and I can test", it felt like unlocking a new level. We could never have tested swimming pool or fan coil support without those volunteers.

Community testers also helped catch subtle bugs: wrong temperature readings, incorrect operation status mapping, credential management issues.

The Result

Today, the Hitachi CSNet Home integration is a complete Home Assistant custom component with:

• Climate entities per zone with HVAC modes (heat/cool/off), presets (comfort/eco), and target temperature control

• Water heater entity with eco/performance modes

• 40+ sensors for temperatures, operation status, alarm monitoring, compressor stats, and more

• Advanced features: silent mode, fan speed control, OTC (Outdoor Temperature Compensation) monitoring

• Alarm system with persistent notifications and historical alarm tracking

• Multi-zone support for C1/C2 air and water circuits

Numbers that tell the story:

AI vs Manual: The Time Factor

Let me be honest about what AI did and didn't do in this project.

What AI excelled at:

• Code translation (JS → Python): The AI could read JavaScript source code, understand the logic, and produce equivalent Python in minutes — work that would take hours manually

• Pattern recognition: Mapping cryptic field names to meaningful constants across thousands of lines of JS

• Boilerplate generation: Home Assistant integration structure, config flows, entity platforms — all the scaffolding that takes time to write but follows clear patterns

• Issue decomposition: Breaking a complex project into well-structured, implementable user stories

What AI couldn't do:

• Test with real hardware. Only real devices connected to the CSNet cloud can validate the integration works

• Understand edge cases from a single data point. AI could map elementType: 1 to "air circuit", but it couldn't know that elementType: 5 encodes temperature differently (multiplied by 10) without seeing the JS logic

• Replace community interaction. Understanding that some users have legacy fan coils with a different speed mapping required human conversation and debugging

The time comparison:

• With AI: Core integration in 2-3 days. Full-featured with community refinement in a few weeks

• Without AI (estimated): Core integration would take 2-3 weeks of reading JavaScript, understanding protocols, writing Python manually. Full-featured? Months.

The AI didn't save 80% of the thinking — it saved 80% of the typing and translating. The human work remained essential: making architectural decisions, reviewing code, testing on real hardware, and working with the community.

Your Turn: A Recipe for Reverse-Engineering Any Web Service

If you want to apply this approach to another undocumented web service, here's the step-by-step:

1. 🔍 Inspect the Network Traffic

• Open DevTools → Network tab

• Interact with the web app and identify the API calls

• Look for JSON responses — that's your best-case scenario

2. 📖 Read the JavaScript Source

• Check the Sources tab for unminified JS

• Use prettier or your IDE to format minified code

• Look for constants, enums, mapping functions

3. 🤖 Feed Everything to an AI

• Give the AI: JavaScript source + sample JSON responses + context about what the web app does

• Ask it to: map every field, identify the data model, create a technical specification

• Use a capable model (Claude Opus, GPT-5.x) for this architectural analysis

4. 📋 Create Structured Issues

• Ask the AI to produce detailed GitHub issues from the spec

• Each issue = one feature, with acceptance criteria and technical notes

• Organize into milestones (core features first, then enhancements)

5. 💻 Implement with AI Assistance

• Use a coding AI (Claude Sonnet, Copilot) to implement each issue

• Keep PRs focused and small

• Always review the code yourself — AI makes subtle mistakes

6. 👥 Release Early, Get Community Feedback

• Don't wait for perfection

• Users with different configurations will find things you never could

• Make it easy for them to share data (JSON responses, debug logs)

Final Thoughts

What I built here with AI could absolutely be done manually. The process of inspecting network calls, reading JavaScript, understanding data formats — it's all standard reverse-engineering. Developers have been doing it for decades.

But the timeframe is completely different. What took days with AI would have taken weeks without it. The AI handled the tedious translation work — reading thousands of lines of JavaScript, mapping constants, generating boilerplate — while I focused on what humans do best: architecture, testing, and community collaboration.

The real magic wasn't just the AI. It was the combination of AI-accelerated development and a community of 4-5 dedicated users, each with a unique Hitachi configuration, who gave regular feedback, tested features they needed, and helped the integration grow from a proof of concept into something that genuinely works for everyone.

Links:

• 📦 Repository: github.com/mmornati/home-assistant-csnet-home

• 📚 Documentation: mmornati.github.io/home-assistant-csnet-home

• 💬 Discussions: GitHub Discussions

• 🛒 HACS: Search for "csnet home" or "Hitachi"

Have you reverse-engineered a web service with AI? Found a cloud-only IoT device that needed a local integration? I'd love to hear about your experience — leave a comment or open a discussion on the repo!

Mais soyons honnêtes : le métier que j'ai exercé pendant trois décennies n'existe plus vraiment.

En tant que Director of Engineering, et avec le recul de 30 ans de développement, je vois beaucoup de débats stériles sur la question "L'IA va-t-elle remplacer les devs ?". C'est, à mon sens, la mauvaise question. L'IA code déjà à notre place. L'acte même d'écrire le code syntaxique, cette "tâche artisanale" que nous avons chérie, est devenue une commodité.

La vraie question est : qu'allons-nous construire maintenant que nous n'avons plus besoin de poser chaque brique à la main ?

De l'Assistant au Partenaire d'Architecture

Il y a encore trois ans, nous utilisions des "copilotes". C'était sympathique : une autocomplétion intelligente qui nous épargnait d'aller sur StackOverflow pour une Regex ou une fonction boilerplate.

Aujourd'hui, en 2026, le paradigme a changé. Nous sommes passés de l'assistant au membre d'équipe synthétique. Les LLM (Large Language Models) actuels ne se contentent plus de répondre ; ils connaissent l'architecture, effectuent des code reviews, proposent des refactorings sur des modules entiers et comprennent les dépendances invisibles dans notre monolithe ou nos microservices.

Selon le rapport GitHub Octoverse 2025, plus de 60% du code mis en production aujourd'hui n'a pas été initialement tapé par un humain. Nous sommes devenus des éditeurs, des superviseurs, des garants de la vision.

Le mythe du Senior irremplaçable (et la réalité du contexte)

On entend souvent : "L'IA remplacera les Juniors, mais les Seniors sont à l'abri car ils ont l'expérience."

C'est une vision dangereusement simpliste. Ce qui distingue un Senior d'un Junior, ce n'est pas seulement sa capacité à écrire du C++ ou du Python les yeux fermés. C'est le contexte. Le Senior sait pourquoi telle décision a été prise il y a trois ans (souvent suite à un incident douloureux en prod), il connaît la "culture" du code de l'entreprise.

Le problème, c'est que cette documentation est souvent tribale, stockée dans nos têtes.

Mais que se passe-t-il quand nous donnons ce contexte à l'IA ? Dans les entreprises modernes, nous ne nous contentons plus de donner un IDE à l'IA. Nous lui ouvrons nos Architecture Decision Records (ADR), nos post-mortems d'incidents, notre documentation Confluence et l'historique de nos PRs. C'est le principe du RAG (Retrieval-Augmented Generation) poussé à l'échelle organisationnelle.

Si on "onboarde" une IA comme on le fait pour un Senior, en lui donnant accès à la mémoire de l'entreprise, elle commence à prendre des décisions d'une maturité surprenante. Elle ne remplace pas le Senior sur la politique ou l'humain, mais sur la technique pure ? La barrière s'effondre.

L'Histoire se répète : La quête de l'efficience

En 30+ ans dans le code, dont 20+ de carrière, j'ai vu ce film plusieurs fois.

• Il y a eu l'époque où un "Senior" était celui qui gérait sa mémoire manuellement et connaissait l'assembleur.

• Puis les langages de haut niveau sont arrivés.

• Puis Internet et les frameworks ont rendu la connaissance syntaxique moins critique.

• L'IDE a apporté l'autocomplétion.

À chaque étape, on a cru que c'était la fin de l'expertise. À chaque étape, la définition de la performance a changé. Le bon développeur n'était plus celui qui écrivait vite, mais celui qui trouvait la solution vite.

Avec l'IA, nous vivons le même changement, mais à une échelle logarithmique. La valeur n'est plus dans la production de la solution (le code), mais dans la définition du problème et la validation du résultat.

L'Analogie Automobile : Sommes-nous les ouvriers des années 80 ?

C'est peut-être l'analogie la plus pertinente pour notre industrie. Au 20ème siècle, les usines automobiles étaient remplies d'ouvriers qui assemblaient des pièces manuellement. Puis, les robots sont arrivés sur les chaînes de montage.

Les ouvriers ont-ils tous disparu ? Non. Mais leur métier a muté. Ils ont arrêté de visser des boulons pour devenir des superviseurs de robots, des techniciens de maintenance, ou des concepteurs de processus. La production a explosé, la qualité s'est standardisée.

Dans le logiciel, nous y sommes.

• Hier : Une équipe de 20 développeurs pour sortir une application complexe.

• Aujourd'hui (2026) : Une "Micro-team" de 3 ou 4 personnes. Un Product Manager technique, un Architecte Système (ex-Senior Dev), et un Quality Engineer, tous assistés par une flotte d'agents IA.

On ne code plus pour la machine, on conçoit pour l'humain. Notre point d'entrée est l'intention (le prompt, la spec), et notre point de sortie est la vérification (est-ce que ça marche ? est-ce que c'est ce qu'on voulait ?). Tout ce qui est au milieu, la "fabrication" du code, est délégué.

Conclusion : Ne restons pas tétanisés

Alors, allons-nous perdre notre job ? Ceux qui restent tétanisés dans la peur, accrochés à l'idée que "pisser du code" est leur unique valeur ajoutée : oui, probablement.

Mais pour ceux qui embrassent la tendance, c'est l'âge d'or. Nous sommes libérés des tâches répétitives. Nous pouvons nous concentrer sur l'architecture, la sécurité, l'expérience utilisateur et la logique métier complexe.

Le titre de "Développeur" changera peut-être. Nous deviendrons des "Architectes de Solutions", des "Ingénieurs Produit" ou des "Superviseurs d'IA". Peu importe le titre. L'important est de comprendre que notre rôle n'est plus de tenir la truelle, mais de dessiner la cathédrale.

Formons-nous. Adaptons-nous. Et acceptons que notre plus grande compétence, en 2026, n'est pas de savoir comment coder, mais de savoir quoi coder.

Et vous, comment a évolué votre quotidien de dev ces 2 dernières années ? On en discute en commentaire.

If you're using AI coding assistants like GitHub Copilot, Cursor, or Claude, you might not realize how much you're spending on context. Every time your AI needs to understand your codebase, it consumes tokens: the currency of large language models (LLMs).

But what are tokens, exactly?

Think of tokens as the "words" that AI models understand. They're not exactly words, but pieces of text:

• "Hello, world!" = 4 tokens

• A 500-line Python file ≈ 2,000–4,000 tokens

• Your entire codebase? Potentially hundreds of thousands of tokens

And here's the kicker: you pay for every token. With GPT-4o, that's $2.50 per million input tokens and $10 per million output tokens. It adds up fast.

The Problem: Traditional Context is Expensive

When an AI assistant needs to understand your code, it typically does one of these things:

Real example: To understand how a search function works in a project, an AI might need to read:

• server.py (1,405 lines → 10,270 tokens)

• database.py (554 lines → 3,514 tokens)

That's 13,784 tokens just to find a few relevant functions.

The Solution: RAG (Retrieval-Augmented Generation)

RAG is a technique that retrieves only the relevant pieces of information before sending them to the AI. Instead of dumping entire files into the context, RAG:

1. Pre-indexes your codebase into semantic chunks (functions, classes, documentation sections)

2. Searches for the most relevant chunks using vector similarity

3. Returns only what's needed (typically 500–2,000 characters per result)

Same example with RAG:

• Search for "search semantic similarity" → returns 5 targeted chunks

• Token cost: 1,679 tokens (vs 13,784)

• Savings: 87.8%

Real Benchmark Results

I built a benchmark script to measure actual token savings using live RAG searches against an indexed codebase.

Verified Results (Real RAG Searches)

These results use actual semantic search against the nexus-dev project's indexed database:

Note: The "MCP gateway routing" case shows lower savings (41.6%) because the RAG search returned one large chunk (2,174 tokens). This demonstrates that RAG effectiveness depends on how your code is chunked: smaller, focused functions yield better savings.

What the RAG Search Actually Returns

For "Find embedding function", instead of 585 lines of embeddings.py, RAG returns:

🔍 embed: 55 tokens          (core embedding function)
🔍 embed_batch: 207 tokens   (batch processing)  
🔍 embed: 59 tokens          (alternative implementation)
🔍 _get_embedder: 92 tokens  (factory function)
🔍 embed: 162 tokens         (another variant)
─────────────────────────────
Total: 575 tokens (vs 3,883 for full file)

Cost Impact

Using GPT-4o pricing ($2.50/1M input tokens):

*Assuming 200 coding sessions per month with 10 context retrievals each

How RAG Works (For Non-Experts)

Let me break down RAG without the jargon:

Step 1: Indexing (One-Time Setup)

Your Code                    Vector Database
┌─────────────────┐         ┌─────────────────┐
│ def login():    │         │ [0.12, 0.45...] │ ← "login function"
│   check_auth()  │   →     │ [0.33, 0.21...] │ ← "authentication"
│   ...           │         │ [0.67, 0.89...] │ ← "user session"
└─────────────────┘         └─────────────────┘

Each function, class, and documentation section is converted into a vector: a list of numbers that represents its meaning. Similar concepts have similar vectors.

Step 2: Searching (Every Query)

When you ask "how does authentication work?", RAG:

1. Converts your question into a vector

2. Finds the most similar vectors in the database

3. Returns the corresponding code chunks

Query: "authentication"
   ↓
Vector: [0.35, 0.22, ...]
   ↓
Match: login() function (similarity: 0.92)
   ↓
Return: Just the relevant 50 lines, not the entire file

Step 3: AI Response

The AI receives only the relevant chunks, answers your question, and you save tokens.

Tools to Measure Your Own Token Usage

LiteLLM (Free, Open-Source)

LiteLLM is an open-source proxy that logs every LLM request with token counts and costs.

Quick setup:

# Install
pip install litellm

# Run as proxy
litellm --model openai/gpt-4o --port 4000

Then point your AI tools at http://localhost:4000 instead of the OpenAI API directly. LiteLLM logs:

• Input/output token counts

• Cost per request

• Latency

View the dashboard:

litellm --config config.yaml --detailed_debug
# Dashboard at http://localhost:4000/ui

OpenAI Usage Dashboard

If you're using OpenAI directly, check your usage dashboard to see daily token consumption.

Implementing RAG for Your Codebase

Option 1: Nexus-Dev (MCP Server)

Nexus-Dev is an open-source project that provides RAG as an MCP (Model Context Protocol) server. It works with Cursor, Copilot, Antigravity, and other MCP-compatible tools.

# Install
pip install nexus-dev

# Initialize your project
cd your-project
nexus-init --project-name "my-project"

# Index your code
nexus-index src/ docs/ -r

Now your AI assistant can use semantic search instead of reading entire files.

Option 2: LangChain + Vector DB

For custom implementations, use LangChain with a vector database like LanceDB, Pinecone, or ChromaDB:

from langchain.embeddings import OpenAIEmbeddings
from langchain.vectorstores import LanceDB

# Index code
embeddings = OpenAIEmbeddings()
vectorstore = LanceDB.from_documents(documents, embeddings)

# Search
results = vectorstore.similarity_search("authentication function", k=5)

When NOT to Use RAG

RAG isn't always the best choice:

RAG shines when:

• ✅ You have a large codebase (>10K lines)

• ✅ You ask repeated questions about the same code

• ✅ You need cross-project knowledge

• ✅ You want to reduce ongoing costs

MCP Gateway for Tool Consolidation

Beyond RAG for code search, there's another token efficiency win: tool consolidation.

The Problem: Tool Definitions Are Expensive

Every MCP tool you expose to an AI consumes tokens in the system prompt. Each tool definition includes:

• Name and description (~20-50 tokens)

• Parameter schemas with types and descriptions (~50-150 tokens)

With multiple MCP servers, this adds up quickly:

And there's a hard limit: VS Code and OpenAI cap tools at 128 per request.

The Solution: Gateway Consolidation

Instead of exposing all 36 tools directly, nexus-dev's gateway approach exposes just 3 meta-tools:

1. search_tools - Find tools by natural language description

2. get_tool_schema - Get full parameter details for a tool

3. invoke_tool - Execute any backend tool

Benchmark Results

The Trade-off

The gateway isn't free: it requires an extra call to discover tools:

Traditional: [Request with 36 tools] → Response
Gateway:     [Request with 3 tools] → search_tools → invoke_tool → Response

When is the gateway worth it?

• ✅ More than ~10 tools across servers (break-even point)

• ✅ Tools you don't use every request

• ✅ Approaching the 128 tool limit

• ❌ Only 2-3 frequently-used tools (direct exposure is simpler)

Run the Benchmark

python scripts/benchmark_gateway_tools.py --servers github,homeassistant,filesystem

Impact Analysis

Per-Request Savings

• 2,406 tokens saved per request

• At $2.50/1M tokens (GPT-4o input): $0.006015 per request

Session Savings (100 requests/session)

• Tokens saved: 240,600

• Cost saved: $0.6015

Monthly Savings (1000 sessions × 100 requests)

• Tokens saved: 240,600,000

• Cost saved: $601.50

Key Takeaways

1. Token costs add up fast: Reading files directly can consume 20x more tokens than needed

2. RAG reduces context costs by 80%+: By returning only relevant chunks

3. Tool definitions are hidden costs: 36 exposed tools = 3,678 tokens every request

4. Gateway consolidation saves 86%: 36 tools → 3 meta-tools = massive savings

5. Measure before optimizing: Use the benchmark scripts on your actual setup

6. There are trade-offs: Gateway adds discovery calls, but saves on baseline

Try It Yourself

1. Clone the benchmark script:

    git clone https://github.com/mmornati/nexus-dev.git
    cd nexus-dev
    pip install tiktoken
    python scripts/benchmark_rag_efficiency.py --project-dir .
   

2. Set up LiteLLM to track your current token usage

3. Implement RAG using Nexus-Dev or your preferred stack

4. Compare before/after costs over a month

Resources

• Nexus-Dev GitHub - Open-source RAG for AI coding assistants

• LiteLLM - Open-source LLM proxy with cost tracking

• OpenAI Tokenizer - Visual token counter

• Tiktoken - Python library for counting tokens

Have questions or want to share your own benchmark results? Open an issue on GitHub or reach out on Mastodon.

But after using MCP on real projects for a while, I hit a wall. Tools are great, but they are passive. They wait for you to drive. I didn't just want a smarter CLI; I wanted a pair programmer. I wanted Agents.

Today, I'm excited to share a major update to Nexus-Dev that brings true, configurable AI Agents to your IDE, powered by the MCP protocol.

Tools vs. Agents: What's the Difference?

Before we dive into the implementation, let's clarify the shift.

A Tool is a stateless function. readFile(path) is a tool. It does exactly one thing when asked. An Agent is a system with a Goal, a Persona, and Memory.

Andrew Ng highlighted back in 2024 the power of "Agentic workflows": where an AI iteratively plans, executes, and critiques its own work. Two years later, this is no longer just a theory; it's how we build software. Gartner now predicts that 40% of enterprise applications will embed task-specific AI agents by 2026, and we're seeing this unfold in real time.

In Nexus-Dev, we're moving from:

User: "Find the file auth.py. Now read it. Now find the login function. Now explain it."

To:

User: "Ask the Security Auditor to review the authentication flow."

Introducing Dynamic Agents

With the latest release, Nexus-Dev scans your project for an agents/ directory. Inside, you can define your own specialized AI team members using simple YAML files.

Here is what agents/code_reviewer.yaml might look like:

name: "code_reviewer"
display_name: "Code Reviewer"
description: "Delegate code review tasks to the Code Reviewer agent."

profile:
  role: "Senior Code Reviewer"
  goal: "Identify bugs, security issues, and suggest improvements"
  backstory: "Expert developer with 10+ years of experience in code quality."
  tone: "Professional and constructive"

memory:
  enabled: true
  rag_limit: 5
  search_types: ["code", "documentation", "lesson"]

When you start your IDE, Nexus-Dev automatically registers a new MCP tool called ask_code_reviewer. When you invoke it, the server instantiates that specific persona, loads its specific memory context, and executes the task.

Getting Started with Templates

You don't need to write these from scratch. We've added a CLI command to generate them from best-practice templates:

# List available templates
nexus-agent templates
📋 Available Agent Templates:

  • API Designer (api_designer)
    Role: API Architect
    Model: claude-sonnet-4.5

  • Code Reviewer (code_reviewer)
    Role: Senior Code Reviewer
    Model: claude-sonnet-4.5

  • Debug Detective (debug_detective)
    Role: Debugging Specialist
    Model: claude-sonnet-4.5

  • Documentation Writer (doc_writer)
    Role: Technical Writer
    Model: claude-opus-4.5

  • Performance Optimizer (performance_optimizer)
    Role: Performance Engineer
    Model: gemini-3-pro

  • Refactor Architect (refactor_architect)
    Role: Refactoring Expert
    Model: gemini-3-deep-think

  • Security Auditor (security_auditor)
    Role: Security Analyst
    Model: claude-opus-4.5

  • Test Engineer (test_engineer)
    Role: QA Engineer
    Model: gpt-5.2-codex

# Create a new agent based on a template
nexus-agent init nexus_doc_writer --from-template doc_writer
✅ Created agent from template: doc_writer
✅ Created agent: /Users/mmornati/Projects/nexus-dev/agents/nexus_doc_writer.yaml

Next steps:
  1. Edit /Users/marco/nexus-dev/agents/nexus_doc_writer.yaml to customize your agent
  2. Restart the MCP server to activate this agent
  3. Use the 'ask_nexus_doc_writer' tool in your IDE

Available templates include: code_reviewer, doc_writer, debug_detective, refactor_architect, test_engineer, security_auditor, api_designer, and performance_optimizer.

The Technical Challenge: The "Refresh" Workaround

Now, let's talk about the specific challenges of building this on top of MCP. It wasn't all smooth sailing.

The "Which Project?" Problem

MCP servers are often global system processes (started by your IDE configuration). But your agents are local to your project. When you open VS Code or Cursor, the MCP server starts up, but it doesn't inherently know that you just opened /Users/marco/projects/my-app. It just runs.

This means we can't efficiently pre-load your project-specific agents at startup because we don't know where "here" is yet.

The MCP Specification Today

If you've been following MCP, you know the protocol has matured significantly. The June 2025 update introduced structured tool outputs (making tool responses more reliable) and OAuth-based authorization. The November 2025 revision added the Tasks primitive for asynchronous, long-running operations and improved server discovery via .well-known URLs.

Crucially, the spec has long supported notifications/tools/list_changed: a mechanism for servers to tell clients "my tool list has changed, please re-fetch it."

The Client Support Gap

The problem isn't the protocol; it's the client implementations.

Ideally, when you open a project, the client (IDE) would:

1. Tell the server "Hey, I'm in this folder."

2. The server would emit notifications/tools/list_changed.

3. The client would re-fetch the tool list.

In practice:

1. Context Awareness: Passing the current working directory reliably during the initialization handshake isn't always standardized across different clients.

2. Notification Handling: Not all clients react instantly to notifications/tools/list_changed. Some cache tool lists aggressively. Some don't implement the notification handler at all.

3. Sampling Support: For agents to work, the client must support the MCP Sampling capability (allowing the server to request LLM completions). Not all IDEs fully support this yet.

This is an evolving landscape. As MCP clients mature, these gaps will close.

The Solution: refresh_agents

To bridge this gap today, we introduced a pragmatic workaround: the refresh_agents tool.

When you start a session, or if you add a new agent YAML file, you (or the model) simply invoke:

refresh_agents()

This forces the Nexus-Dev server to:

1. Query the IDE for the current active project path (discovered via NEXUS_PROJECT_ROOT environment variable or inferred from context).

2. Scan the agents/ folder.

3. Dynamically register the ask_<agent_name> tools.

4. Emit notifications/tools/list_changed to tell the client to update its UI.

It's a small extra step, but it unlocks the ability to have per-project, fully customized AI teams without needing complex global configuration management.

Tip: The ideal setup is to configure your IDE's MCP settings with NEXUS_PROJECT_ROOT pointing to your project. This eliminates the need for manual refresh in most cases. See the Quick Start Guide for configuration examples.

Why This Matters

This update transforms Nexus-Dev from a "RAG Search Engine" into a "Team Management System" for your AI. You can now curate the exact help you need.

• Refactoring? Spin up a refactor_architect.

• Writing Docs? Use the doc_writer.

• Learning a new codebase? Ask the onboarding_buddy.

The shift from tools to agents mirrors the broader trend in software development: we're moving from commanding machines to collaborating with them. Your AI isn't just a faster grep; it's a teammate with a defined role and responsibility.

What's Next?

The MCP ecosystem is evolving fast. I'm keeping an eye on:

• Better client-side tooling: As IDEs like Cursor and VS Code mature their MCP implementations, the need for refresh_agents will diminish.

• Multi-Agent Collaboration: The ability to have agents talk to each other, a security_auditor that flags issues, which a code_reviewer then addresses, is an active area of research.

• Server Discovery: The MCP Registry (now in general availability preview) will make sharing and discovering useful agents much easier.

Go ahead and give it a try. The future of coding isn't just about faster typing; it's about better delegating.

Check out the documentation on GitHub to get started.

⚠️ "You have configured more than 50 tools. This may degrade performance."

Modern AI coding agents connect to multiple MCP (Model Context Protocol) servers: GitHub, PostgreSQL, Filesystem, Slack, Jira... Each server exposes multiple tools. Before you know it, you're at 50+ tools, and your AI agent starts struggling.

In this article, I'll explain why this happens and how Nexus-Dev solves it with a Gateway architecture that reduces tool count from 50+ down to just 11.

Quick Context: What is MCP?

MCP (Model Context Protocol) is a standard introduced by Anthropic in November 2024 that allows AI assistants to connect to external tools and data sources. When you install a GitHub MCP server, your AI can create issues, open PRs, and manage repositories.

The problem? Each MCP server adds more tools to your AI's context, and there's a limit to how many tools work well together.

The Problem: Tool Explosion

How Tools Consume Context

When you configure MCP servers, each tool's definition (name, description, parameters) gets injected into the AI's context window:

5 servers × 10 tools = 50 tools consuming precious context.

Why Performance Degrades

Research shows that AI accuracy can drop from 87% to 54% with context overload. Each tool definition takes tokens away from your actual code and conversation. Platforms like Cursor enforce a hard limit around 40-50 tools to prevent this.

But What About Per-Project Configuration?

Modern IDEs now support project-level MCP configuration:

• VS Code: .vscode/mcp.json

• Cursor: .cursor/mcp.json

This is better than global configuration: you only load relevant servers per project. But even a typical full-stack project might need GitHub + Database + Cloud + Monitoring + Communication tools. That's still 40+ tools for a single project.

The Solution: Nexus-Dev as a Gateway

Instead of exposing all tools directly, Nexus-Dev acts as a gateway: a single MCP server that proxies requests to any number of backend servers.

The key insight: Your AI agent only sees 11 tools, but can access all 50+ through dynamic discovery.

How It Works

1. AI asks: "I need to create a GitHub issue"

2. Nexus-Dev searches its RAG index: finds github.create_issue

3. AI invokes: invoke_tool("github", "create_issue", {...})

4. Nexus-Dev proxies the request to GitHub MCP

5. Result returned to AI

All through just 11 gateway tools, not 50+.

The 11 Gateway Tools

Instead of exposing 50+ tools directly, your AI sees:

RAG Tools (7): from the previous article:

• search_code, search_docs, search_lessons, search_knowledge

• index_file, record_lesson, get_project_context

Gateway Tools (4): for accessing any backend:

Implementation: How It Works

1. Index Tool Documentation

First, index all your MCP servers' tools into the RAG database:

# Index all configured servers
nexus-index-mcp --all

# Or index a specific server
nexus-index-mcp --server github

This stores each tool's description and schema for semantic search.

2. Semantic Tool Discovery

When the AI asks "how do I create a GitHub issue?", it calls search_tools:

# search_tools("create github issue")
# Returns: github.create_issue - Creates a new issue
#          Parameters: owner, repo, title, body...

The AI finds the right tool by meaning, not by knowing every tool name upfront.

3. Tool Invocation with Error Handling

# AI invokes through the gateway
invoke_tool("github", "create_issue", {
    "owner": "mmornati",
    "repo": "nexus-dev",
    "title": "Fix login bug"
})

Nexus-Dev handles:

• Connection pooling and reuse

• Automatic retry with exponential backoff

• Configurable timeouts

• Clean error messages

4. Server Configuration

Servers are configured in .nexus/mcp_config.json:

{
  "version": "1.0",
  "servers": {
    "github": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://..."]
    }
  }
}

Two transport types supported:

• stdio: Local processes (npm packages, python scripts)

• sse: Remote HTTP servers (cloud-hosted MCP endpoints)

Quick Setup

# Import from your existing global MCP config
nexus-mcp init --from-global

# Or add servers manually
nexus-mcp add github --command "npx" --args "-y" \
  --args "@modelcontextprotocol/server-github"

# Index all tool documentation
nexus-index-mcp --all

Update your IDE to use only Nexus-Dev:

{
  "mcpServers": {
    "nexus-dev": { "command": "nexus-dev" }
  }
}

That's it. One server. 11 tools. Access to everything.

Before vs After

Before: Traditional Setup

IDE Config:
  github:         (15 tools)
  postgres:       (8 tools)
  filesystem:     (10 tools)
  slack:          (12 tools)
  linear:         (8 tools)

Total: 53 tools in context
⚠️ Warning: Too many tools

After: Gateway

IDE Config:
  nexus-dev:      (11 tools)

✅ All 53+ tools accessible via gateway
✅ Minimal context usage
✅ No performance degradation

Real Example

You: "Create a GitHub issue for the login bug"

AI: Let me find the right tool...
    [search_tools("create github issue")]

    Found: github.create_issue

    [invoke_tool("github", "create_issue", {
        "owner": "mmornati",
        "repo": "nexus-dev",
        "title": "Fix login redirect loop",
        "labels": ["bug"]
    })]

    ✅ Issue #42 created

All through Nexus-Dev's 11 tools.

Benefits Summary

Conclusion

The MCP ecosystem is growing fast, and tool explosion is a real problem. By using Nexus-Dev as a gateway:

• Your AI agent sees only 11 tools

• It can access 50+ tools through semantic search

• Context usage stays minimal

• Configuration stays simple

Combined with the RAG capabilities from the previous article, Nexus-Dev becomes a complete solution for making your AI coding agent smarter and more efficient.

Nexus-Dev is open source: github.com/mmornati/nexus-dev

Every single time I start a new session, my AI assistant has to re-learn my codebase. It scans files, asks me the same questions, and burns through tokens just to understand context it already knew yesterday. It's like working with a brilliant colleague who gets amnesia every night.

So I built Nexus-Dev, an open-source local RAG system that gives AI coding agents persistent memory.

What is RAG? (For Those New to AI)

Before diving in, let's clarify some terms:

RAG (Retrieval-Augmented Generation) is a technique where, instead of feeding an entire document to an AI, you store information in a searchable database and retrieve only the relevant pieces when needed. Think of it like giving the AI a smart index to your codebase rather than making it read everything.

MCP (Model Context Protocol) is an open standard introduced by Anthropic that allows AI agents to connect to external tools and data sources. If you've used GitHub Copilot, Cursor, or Claude with plugins, you're already using MCP.

Embeddings are numerical representations of text that capture meaning. Similar texts have similar embeddings, which enables semantic search, finding content by meaning, not just keywords.

The Problem: AI Agents Have Amnesia

No Memory Between Sessions

When you close your IDE and reopen it the next day, your AI assistant forgets everything. It doesn't remember the architecture decisions you made, the bugs you fixed together, or the patterns your codebase uses.

Token Consumption Adds Up

Every session, the AI needs to "warm up" by reading your codebase again. This consumes tokens, and tokens cost money. Research shows that giving AI agents more context can actually make them perform worse. Accuracy can drop significantly (from 87% to 54%) due to context overload.

Existing Solutions Are Cloud-Based

Several solutions address this problem:

• Qodo: RAG-based code intelligence (proprietary)

• Zep and Pieces: Agent memory platforms (cloud-based)

But I wanted something local-first (my code never leaves my machine), open-source (I control the stack), and cross-project (knowledge learned in one project helps others).

The Solution: How Nexus-Dev Works

The diagram shows the two main flows:

Indexing (top flow): Source code → Chunker → Embeddings → LanceDB Search (bottom flow): Query → Embeddings → LanceDB → Relevant Results

Step 1: Language-Aware Chunking

The first insight is that naive text splitting doesn't work for code. Cutting a function in half destroys its meaning.

Instead, Nexus-Dev uses tree-sitter to parse code into an Abstract Syntax Tree (AST) and extract semantic units: functions, classes, and methods.

# Each chunk contains rich metadata for better search
@dataclass
class CodeChunk:
    content: str           # The actual code
    chunk_type: ChunkType  # function, class, method
    name: str              # e.g., "authenticate_user"
    docstring: str | None  # Documentation helps search!
    signature: str | None  # Function signature
    start_line: int        # Precise location
    end_line: int

Supported languages: Python, JavaScript/TypeScript, Java, and Markdown/RST for documentation.

Step 2: Multi-Provider Embeddings

Embeddings convert code chunks into vectors that capture meaning. Nexus-Dev supports multiple providers:

⚠️ Important: Embeddings aren't portable between providers. Switching requires re-indexing.

For privacy-focused teams, Ollama runs entirely locally:

{
  "embedding_provider": "ollama",
  "embedding_model": "nomic-embed-text"
}

Step 3: LanceDB Vector Storage

LanceDB is a local vector database, no server to run, just a file on disk.

# Semantic search finds code by meaning, not keywords
results = database.search(
    query="authentication middleware",
    doc_type=DocumentType.CODE,
    limit=5
)
# Returns the most relevant functions/classes

Step 4: The Secret Weapon: Lessons Learned

After fixing a tricky bug, record it:

record_lesson(
    problem="JWT validation fails with special characters",
    solution="Use base64url decode instead of base64",
    code_snippet="claims = base64url.decode(token.split('.')[1])"
)

Next time you encounter a similar issue, the AI finds it automatically. This creates institutional memory that survives team changes.

Getting Started

# Install
pip install nexus-dev

# Initialize
cd your-project
nexus-init --project-name "my-project" --embedding-provider openai

# Set API key
export OPENAI_API_KEY="sk-..."

# Index your code
nexus-index src/ docs/ -r

# Verify
nexus-status

Add to your IDE's MCP configuration:

For Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "nexus-dev": { "command": "nexus-dev" }
  }
}

For VS Code (.vscode/mcp.json):

{
  "mcpServers": {
    "nexus-dev": { "command": "nexus-dev" }
  }
}

The 7 Tools Your AI Gets

Real Example

You: "I need to add authentication to the API"

AI: Let me search the codebase...
    [Calls search_code("authentication middleware")]

    Found 3 relevant results:
    1. auth_middleware.py:15-45 - JWTAuthMiddleware class
    2. user_service.py:23-67 - authenticate_user function

No more reading through entire files. The AI finds exactly what's relevant.

Results

Since deploying Nexus-Dev:

• Faster session starts: AI immediately has context

• Reduced token usage: Only fetching what's needed

• Cross-project learning: Lessons from one project help others

• All local: No cloud, no API costs for storage

Nexus-Dev is open source: github.com/mmornati/nexus-dev

So I did what any modern developer would do: I asked my AI coding assistants for help.

And what happened next was pretty remarkable.

The Problem: Generic Security Tools Don't Understand Your App

If you've ever run a security scanner like OWASP ZAP or Burp Suite against your application, you know the drill: you get a bunch of findings about missing headers, potential XSS vectors, and maybe some SQL injection warnings. These tools are great. Seriously. Use them.

But here's what they don't understand:

• Your business logic: Can a user manipulate their XP score by submitting the same solution twice?
• Your custom attack surface: Can someone escape your Python sandbox by accessing __builtins__?
• Your architecture: Is your Docker executor properly isolating network access?

Generic scanners test for generic vulnerabilities. But when you're building something unique — like a platform that executes untrusted Python code — you need custom tests that understand YOUR specific risks.

That's the gap I needed to fill.

Enter "Vibe Coding" for Security

If you've read my previous post about building Cyber Code Academy, you know I'm a big fan of what I call "vibe coding" — the practice of describing what you want to AI assistants (Cursor, GitHub Copilot, or in this case, Antigravity) and letting them generate the code.

It turns out this approach works beautifully for security testing.

Here's why: Security knowledge is vast and specialized. Most developers (myself included) don't have encyclopedic knowledge of every attack vector. But AI assistants do. They've been trained on OWASP guides, security research papers, and countless examples of both attacks and defenses.

So instead of trying to remember every possible SQL injection payload, I just described what I wanted:

"I need to test if someone can escape my Python sandbox by using 
getattr() to access __builtins__ and then call exec(). Generate 
a test that attempts this and reports if it succeeds."

And the AI delivered:

def test_namespace_escape_getattr(self):
    """Test namespace escape via getattr"""
    namespace_tests = [
        "getattr(__builtins__, 'exec', None)('print(\"ESCAPED\")')",
        "getattr(__builtins__, '__import__', None)('os').system('id')",
        "getattr(globals(), '__builtins__', {}).get('exec', None)('print(\"ESCAPED\")')",
    ]

    for code in namespace_tests:
        response = self.session.post(
            f"{self.base_url}/api/v1/execute",
            json={
                "code": code,
                "tests": [{"name": "test", "assertion": "True"}],
                "timeout_seconds": 5
            }
        )

        if "ESCAPED" in response.json().get("output", ""):
            self.log_finding(
                "CRITICAL",
                "Namespace escape via getattr",
                "Code can escape restricted namespace using getattr"
            )

I didn't need to know the exact syntax for these bypass techniques — the AI brought that knowledge. I just needed to know what aspect I wanted to test.

Building a Complete Security Test Suite

Over several sessions, I built up a comprehensive security test suite organized into categories that made sense for my application:

security-tests/production/
├── recon.py              # Endpoint discovery
├── test_auth.py          # JWT attacks, token bypass, password policy
├── test_authz.py         # IDOR, role escalation, access control
├── test_injection.py     # SQL injection, XSS, command injection
├── test_code_exec.py     # Sandbox escape, Docker bypass, DoS
├── test_api_security.py  # Rate limiting, headers, CORS
├── test_business_logic.py # XP manipulation, score cheating
└── run_tests.py          # Orchestrator with phased execution

Let me walk you through some of the more interesting tests.

JWT Token Manipulation

One of the classic attacks against JWT-based authentication is the "none algorithm" attack. Here's what the AI generated for me:

def test_jwt_none_algorithm(self):
    """Test JWT 'none' algorithm attack"""
    # Decode token without verification
    decoded = jwt.decode(
        self.access_token, 
        options={"verify_signature": False}
    )

    # Create token with 'none' algorithm
    payload = decoded.copy()
    payload["alg"] = "none"

    malicious_token = jwt.encode(payload, "", algorithm="none")

    # Try to use it
    response = requests.get(
        f"{self.base_url}/api/v1/dashboard/me",
        headers={"Authorization": f"Bearer {malicious_token}"}
    )

    if response.status_code == 200:
        self.log_finding(
            "CRITICAL",
            "JWT 'none' algorithm accepted",
            "Server accepts tokens with 'none' algorithm, allowing forgery"
        )

I honestly didn't know about this attack until the AI generated this test. Now my application correctly rejects these tokens ✓

SQL Injection Payloads

For input validation testing, the AI generated a comprehensive list of SQL injection payloads:

sql_payloads = [
    "' OR '1'='1",
    "' OR '1'='1' --",
    "admin'--",
    "' UNION SELECT NULL--",
    "'; DROP TABLE users; --",
]

for payload in sql_payloads:
    response = self.session.post(
        f"{self.base_url}/api/v1/auth/login",
        json={"username": payload, "password": "Test1234!"}
    )

    # Check for SQL errors in response
    if any(keyword in response.text.lower() 
           for keyword in ["sql", "syntax error", "postgresql"]):
        self.log_finding(
            "CRITICAL",
            "SQL injection in login username",
            f"SQL error detected with payload: {payload}"
        )

Docker Sandbox Escape

Since my platform runs user code in Docker containers, I needed to test for container escape vulnerabilities:

def test_docker_socket_access(self):
    """Test accessing Docker socket"""
    docker_socket_tests = [
        "import socket; s = socket.socket(socket.AF_UNIX); "
        "s.connect('/var/run/docker.sock'); print('DOCKER_ACCESSIBLE')",
        "open('/var/run/docker.sock', 'r')",
    ]

    for code in docker_socket_tests:
        response = self.session.post(
            f"{self.base_url}/api/v1/execute",
            json={"code": code, "timeout_seconds": 5}
        )

        if "DOCKER_ACCESSIBLE" in response.json().get("output", ""):
            self.log_finding(
                "CRITICAL",
                "Docker socket accessible from sandbox",
                "Code can access Docker socket, allowing container escape"
            )

Running the Tests: Real Results

Let me show you what happens when we run this against the live production site. Here's the actual output from a test run I did today:

============================================================
PRODUCTION SECURITY PENETRATION TESTING
============================================================
Target: https://play.pygame.ovh
Test User: aitest_security_2025
Start Time: 2026-01-10T10:10:24
============================================================

PHASE 1: RECONNAISSANCE
============================================================
[+] Found docs at /docs
[+] Found: POST /api/v1/auth/register (Status: 422)
[+] Found: POST /api/v1/auth/login (Status: 422)
[+] Found: GET /api/v1/challenges (Status: 200)
[+] Found: POST /api/v1/execute (Status: 401)
...
[+] Reconnaissance complete. Found 20 endpoints.

PHASE 2: AUTHENTICATION TESTS
============================================================
[+] Test user 'aitest_security_2025' created successfully
[+] Login successful, tokens obtained
[+] JWT 'none' algorithm correctly rejected
[+] Weak password correctly rejected: short
[+] Weak password correctly rejected: nouppercase123
...
[+] Authentication tests complete. Found 0 issues.

PHASE 5: CODE EXECUTION TESTS
============================================================
[*] Testing Docker socket access...
[*] Testing host filesystem access...
[*] Testing network access...
[*] Testing namespace escape via getattr...
[*] Testing import bypass...
...
[+] Code execution tests complete. Found 0 issues.

After approximately 68 seconds of automated testing, here's the summary report:

============================================================
TESTING COMPLETE
============================================================
Total Time: 67.85 seconds
Total Findings: 3
  - Critical: 0
  - High: 0
  - Medium: 3
  - Low: 0
============================================================

What the Tests Found

The test suite automatically generates both JSON and Markdown reports. Here's what it found:

Zero critical or high-severity issues. The sandbox is holding strong — no Docker escapes, no SQL injection, no JWT bypasses. But I've got some housekeeping to do on those security headers.

What AI Gets Right (and Wrong)

After this experience, here's my honest assessment:

AI Excels At:

✅ Generating known attack patterns — OWASP Top 10, common bypass techniques, injection payloads. The AI has seen thousands of examples.

✅ Structuring test suites — Proper organization, error handling, logging. The boilerplate code is solid.

✅ Documentation — Every test includes docstrings explaining what it's testing and why.

✅ Covering edge cases — The AI often suggests test cases I wouldn't have thought of.

Where Humans Are Still Essential:

⚠️ Understanding YOUR threat model — You still need to tell the AI what's important to test.

⚠️ Interpreting results — Is that "Sensitive data in /docs" finding actually a problem? (In my case, it's an intentional feature for developers.)

⚠️ Responsible testing — Never run these tests against systems you don't own or without authorization.

⚠️ Post-exploitation thinking — If an attack succeeds, what's the real-world impact? AI doesn't always connect those dots.

Try It Yourself: A Quick Start Guide

Want to vibe-code your own security tests? Here's how to get started:

1. Define Your Attack Surface

Start by listing what makes your application unique:

• "My app executes user-submitted code"
• "I use JWT tokens with custom claims"
• "Users can modify their profile, including avatar uploads"

2. Prompt by Category

Work through security categories systematically:

"Generate authentication security tests for a FastAPI application 
that uses JWT tokens. Test for: none algorithm attack, token 
manipulation, authentication bypass, and weak password acceptance."

3. Iterate and Refine

After the first generation, ask for improvements:

"Add a test that attempts to access other users' data by 
modifying the user_id in the JWT payload"

4. Review and Understand

Don't just run the tests blindly. Read through the code. Learn why each attack works (or should be blocked). You'll become a better developer in the process.

5. Run Responsibly

Always test in a development environment first. Never attack production systems without explicit authorization. And delete those test accounts when you're done.

Conclusion: Security for Everyone

Here's what I've learned: You don't need to be a security expert to write security tests. You just need to know what questions to ask and have an AI assistant that can provide the answers.

The barrier to entry for security testing just got a lot lower. And that's a good thing — because security shouldn't be a luxury reserved for companies with dedicated pentest teams. If you're building software, you should be testing its security. And now, with AI as your pair programmer, you can.

The complete security test suite I've described is open source (link at the end of this post). Feel free to explore, adapt it to your needs, and contribute improvements. And if you want to see it in action, you can try to break Cyber Code Academy yourself.

Seriously. Give it your best shot :P

The security test suite referenced in this article is open source. If you'd like access to the complete codebase with all 24+ test scripts, feel free to reach out — I'm happy to share more with interested developers.

Related Posts:

• Building Cyber Code Academy: A "Pure Vibe Coding" Experiment
• Securing Python Code Execution: How We Protected Our Server from Untrusted Code

Have questions about AI-assisted security testing? Found a vulnerability I missed? Let me know in the comments or reach out on Twitter!

In this post, I'll walk through how we built a secure, production-ready code execution system using Docker containers, restricted Python namespaces, and multiple layers of defense. We'll explore the attack vectors we protect against, the security measures we implemented, and how each execution flows through our system.

The Risks: What Could Go Wrong?

Before diving into our solution, let's understand the threats. When users can submit arbitrary Python code, attackers can attempt:

1. Namespace Escape

Python's __builtins__ dictionary contains powerful functions like exec(), eval(), compile(), and __import__(). If attackers can access these, they can execute arbitrary code or import dangerous modules.

# Attack attempt: Access exec via getattr
dangerous = getattr(__builtins__, 'exec', None)
if dangerous:
    dangerous("import os; os.system('rm -rf /')")

2. Filesystem Access

Even without dangerous builtins, attackers might try to read sensitive files:

• /etc/passwd — user accounts

• /proc/self/environ — environment variables (potentially containing database URLs, API keys)

• /var/run/docker.sock — Docker socket (would allow container escape)

3. Network Access

Malicious code could exfiltrate data or download malware:

• Make HTTP requests to attacker-controlled servers

• Open socket connections

• Access internal network resources

4. Resource Exhaustion (DoS)

Attackers could consume all server resources:

• Infinite loops consuming CPU

• Large memory allocations

• File descriptor exhaustion

5. Container Escape

If running in Docker, attackers might try to:

• Access the Docker socket to control the host

• Mount the host filesystem

• Break out of container isolation

6. Code Injection

Various Python mechanisms could be exploited to execute arbitrary code:

• eval(), exec(), compile() functions

• __import__() to load dangerous modules

• Metaclass-based attacks

To validate our security, we created a comprehensive test suite with 24 security tests covering all these attack vectors. Every test should fail — if any succeeds, we have a vulnerability.

Our Solution: Defense in Depth

We implemented multiple security layers, each protecting against different attack vectors. If one layer fails, others provide backup protection.

Architecture Overview

┌─────────────────────────────────────┐
│     FastAPI Endpoint                │
│  POST /api/v1/execute               │
│  (Authentication, Validation)       │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│     ExecutorPool Service            │
│  - Semaphore (concurrency limit)    │
│  - Container lifecycle management   │
│  - Resource limit enforcement       │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│     Docker Container                │
│  - Network: none (isolated)         │
│  - Capabilities: ALL dropped        │
│  - Filesystem: read-only            │
│  - Memory: 512MB max                │
│  - CPU: 1 core max                  │
│  - Timeout: 10-30 seconds           │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│  executor_entrypoint.py             │
│  - Restricted namespace             │
│  - Signal-based timeout             │
│  - Test execution                   │
└─────────────────────────────────────┘

Layer 1: Docker Container Isolation

The first line of defense is Docker container isolation. Each code execution runs in a completely isolated container.

The Executor Image

Our executor image (infra/docker/executor.Dockerfile) is purpose-built for security:

FROM python:3.13-slim

# Minimal base image - only essential libraries
RUN apt-get update && apt-get install -y --no-install-recommends \
    libffi-dev \
    libssl-dev \
    && rm -rf /var/lib/apt/lists/*

# Create non-root user
RUN useradd -m -s /sbin/nologin executor

WORKDIR /executor

# Copy executor entrypoint script
COPY --chown=executor:executor executor_entrypoint.py /executor/

# Switch to non-root user
USER executor

ENTRYPOINT ["python", "/executor/executor_entrypoint.py"]

Key security features:

• Minimal base image: python:3.13-slim contains only essential packages

• Non-root user: Code runs as executor user, not root

• No unnecessary packages: Reduces attack surface

Container Security Flags

When we run the container, we apply strict security constraints:

cmd = [
    "docker", "run",
    "--rm",  # Auto-remove after execution
    "--memory=512m",  # Memory limit
    "--memory-swap=512m",  # No swap (prevents swap-based attacks)
    "--cpus=1.0",  # CPU limit
    "--network=none",  # No network access
    "--read-only",  # Read-only root filesystem
    "--cap-drop=ALL",  # Drop all Linux capabilities
    "--tmpfs=/tmp:size=10m,mode=1777",  # Only /tmp writable (10MB limit)
    "-i",  # Interactive stdin for input
    "cyber-code-executor"
]

Let's break down what each flag prevents:

Even if malicious code somehow breaks out of Python's restrictions, Docker isolation prevents it from accessing the host system, network, or other containers.

Layer 2: Restricted Python Namespace

The second layer restricts what Python functions and modules are available to user code. We create a custom __builtins__ dictionary containing only safe functions.

Creating the Restricted Namespace

Inside executor_entrypoint.py, we build a restricted execution namespace:

import builtins

exec_namespace = {
    "__builtins__": {
        # Safe built-in functions
        "print": print,
        "len": len,
        "range": range,
        "str": str,
        "int": int,
        "float": float,
        "list": list,
        "dict": dict,
        "set": set,
        "tuple": tuple,
        "zip": zip,
        "enumerate": enumerate,
        "sorted": sorted,
        "sum": sum,
        "min": min,
        "max": max,
        "abs": abs,
        "all": all,
        "any": any,
        "map": map,
        "filter": filter,
        "bool": bool,
        "isinstance": isinstance,
        "type": type,
        "callable": callable,
        "hasattr": hasattr,
        "getattr": getattr,
        "id": id,

        # Limited exception types
        "Exception": Exception,
        "ValueError": ValueError,
        "TypeError": TypeError,
        "IndexError": IndexError,
        "KeyError": KeyError,

        # Required for class creation
        "__build_class__": builtins.__build_class__,
        "super": super,
    },
    "__name__": "__main__",
    "__doc__": None,
}

# Execute user code in restricted namespace
exec(code, exec_namespace)

What's Blocked?

Notice what's not in the namespace:

• ❌ eval(), exec(), compile() — Code execution

• ❌ __import__() — Module importing

• ❌ open(), file() — File operations

• ❌ input() — User input

• ❌ os, subprocess, sys — System access (not in namespace)

• ❌ socket, urllib, requests — Network access (not in namespace)

Why getattr is Safe

You might notice getattr is allowed. Couldn't attackers use it to access dangerous functions?

# This attack attempt fails:
dangerous = getattr(__builtins__, 'exec', None)

It fails because __builtins__ in our namespace is a dictionary, not the real builtins module. The dictionary only contains the functions we explicitly added. There's no exec key in that dictionary, so getattr returns None.

Timeout Enforcement

We use signal-based timeout enforcement as a safety net:

class TimeoutException(Exception):
    pass

def timeout_handler(signum, frame):
    raise TimeoutException("Code execution exceeded timeout limit")

signal.signal(signal.SIGALRM, timeout_handler)
signal.alarm(timeout_seconds)  # Set timeout

try:
    exec(code, exec_namespace)
finally:
    signal.alarm(0)  # Cancel alarm

The Docker container also has a process-level timeout, providing defense in depth. If user code tries to modify signal handlers, Docker's timeout will still terminate the container.

Layer 3: Execution Flow

Now let's see how everything works together when a user submits code.

1. Request Arrives

A user submits code via the API:

POST /api/v1/execute
{
    "code": "def add(a, b): return a + b",
    "tests": [
        {
            "name": "test_add",
            "assertion": "assert add(2, 3) == 5",
            "hidden": false
        }
    ],
    "timeout_seconds": 10
}

2. ExecutorPool Service

The ExecutorPool service manages container execution:

class ExecutorPool:
    def __init__(self, max_pool_size: int = 5):
        self.semaphore = asyncio.Semaphore(max_pool_size)  # Concurrency limit
        self.executions: Dict[str, ExecutionResult] = {}

    async def execute(self, request: ExecutionRequest):
        async with self.semaphore:  # Limit concurrent executions
            # Prepare input JSON
            execution_input = {
                "code": request.code,
                "tests": request.tests,
                "timeout_seconds": request.timeout_seconds
            }

            # Run in thread pool (Docker is blocking I/O)
            result = await loop.run_in_executor(
                None,
                self._execute_blocking,
                execution_input,
                request.execution_id,
                request.timeout_seconds
            )
            return result

Key features:

• Semaphore: Limits concurrent executions (default: 5)

• Thread pool: Docker operations are blocking, so we run them in a thread pool to avoid blocking the async event loop

• Result caching: Stores results for later retrieval

3. Container Execution

The blocking execution function creates and runs the container:

def _execute_blocking(self, execution_input: dict, execution_id: str, timeout_seconds: int):
    # Build docker run command with all security flags
    cmd = [
        "docker", "run",
        "--rm",
        "--memory=512m",
        "--memory-swap=512m",
        "--cpus=1.0",
        "--network=none",
        "--read-only",
        "--cap-drop=ALL",
        "--tmpfs=/tmp:size=10m,mode=1777",
        "-i",
        "cyber-code-executor"
    ]

    # Run container with JSON input via stdin
    result = subprocess.run(
        cmd,
        input=json.dumps(execution_input),
        capture_output=True,
        text=True,
        timeout=timeout_seconds + 10  # Buffer for container startup
    )

    # Parse JSON output from stdout
    result_data = json.loads(result.stdout)
    return ExecutionResult(**result_data)

4. Inside the Container

The container's entrypoint script (executor_entrypoint.py) reads JSON from stdin:

def main():
    # Read input from stdin
    request = json.loads(sys.stdin.read())

    code = request.get("code", "")
    tests = request.get("tests", [])
    timeout = request.get("timeout_seconds", 10)

    # Execute code in restricted namespace
    result = execute_code(code, tests, timeout)

    # Output results as JSON to stdout
    print(json.dumps(result), file=sys.stdout)
    sys.exit(0)

The execute_code function:

1. Sets up signal-based timeout

2. Creates restricted namespace

3. Executes user code with exec(code, exec_namespace)

4. Runs test assertions in the same namespace

5. Captures stdout/stderr

6. Returns structured results

5. Results Return

The container outputs JSON to stdout, which the backend parses:

{
    "passed": true,
    "test_results": [
        {
            "name": "test_add",
            "passed": true,
            "error": null
        }
    ],
    "error": null,
    "output": "",
    "execution_time_ms": 145
}

The container is automatically removed (--rm flag), ensuring no persistent state.

Security Testing

We maintain a comprehensive security test suite with 24 tests covering all attack vectors. Every test should fail — if any succeeds, we have a vulnerability.

Example Test: Filesystem Access

"""
Test: Attempt to read files from filesystem
Risk Level: HIGH
"""
result = "SAFE"

# Attempt 1: Try using open() directly (should be blocked)
try:
    with open('/etc/passwd', 'r') as f:
        content = f.read()
        result = f"VULNERABLE: Can read /etc/passwd: {content[:100]}"
except Exception as e:
    error_type = type(e).__name__
    if error_type == 'NameError':
        result = "BLOCKED: open() not available"
    else:
        result = f"BLOCKED: open() failed: {str(e)}"

print(result)

Expected result: "BLOCKED: open() not available" (because open is not in the restricted namespace)

Example Test: Docker Socket Access

"""
Test: Attempt to access Docker socket
Risk Level: CRITICAL
"""
result = "SAFE"

# Attempt 1: Try to read Docker socket file
try:
    with open('/var/run/docker.sock', 'rb') as f:
        result = "VULNERABLE: Can read Docker socket"
except:
    pass

# Attempt 2: Try to connect via socket module
try:
    import socket
    s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
    s.connect('/var/run/docker.sock')
    result = "VULNERABLE: Can connect to Docker socket"
except:
    pass

print(result)

Expected result: "SAFE" (because open is blocked and socket cannot be imported)

Test Categories

Our test suite covers:

1. Namespace Escape (4 tests) — Accessing dangerous builtins

2. Filesystem Access (3 tests) — Reading/writing files

3. Network Access (2 tests) — Socket connections, HTTP requests

4. Docker Escape (2 tests) — Docker socket, host filesystem

5. Resource Exhaustion (2 tests) — Memory/CPU DoS

6. Import Bypass (3 tests) — Bypassing import restrictions

7. Code Injection (2 tests) — eval, exec, compile

8. Environment Variables (2 tests) — Credential leakage

9. Advanced Techniques (3 tests) — Metaclass attacks, descriptor abuse

All tests should fail. Running them regularly ensures our security measures remain effective.

Defense in Depth: How Layers Work Together

Each security layer protects against different attack vectors:

1. Docker isolation prevents access to host system, network, and filesystem

2. Resource limits prevent DoS attacks (memory, CPU, timeout)

3. Restricted namespace prevents code injection and dangerous imports

4. Non-root user limits damage if isolation is breached

5. Read-only filesystem prevents file modifications

6. Dropped capabilities prevents privilege escalation

Even if one layer fails, others provide backup protection. For example:

• If namespace escape succeeds → Docker isolation prevents damage

• If Docker escape succeeds → Non-root user limits capabilities

• If resource limits fail → Timeout enforcement terminates execution

Real-World Results

In production, our security measures successfully block all attack attempts:

• ✅ Namespace escape attempts fail (cannot access exec, eval, __import__)

• ✅ Filesystem access attempts fail (open() not in namespace)

• ✅ Network access attempts fail (cannot import socket, network is disabled)

• ✅ Docker escape attempts fail (Docker socket not mounted, network disabled)

• ✅ Resource exhaustion attempts fail (limits enforced, timeouts trigger)

• ✅ Code injection attempts fail (dangerous functions not in namespace)

Users can write normal Python code (functions, classes, data structures, algorithms), but cannot access system resources or execute arbitrary code.

Performance Considerations

Security doesn't come without cost. Our measurements:

• Container startup: ~200-500ms

• Simple execution: ~50-150ms

• Total request time: ~250-650ms

For a learning platform, this is acceptable. The security benefits far outweigh the performance cost.

To optimize:

• Pre-build executor images during deployment

• Use Docker layer caching

• Increase semaphore size for concurrent workloads

• Monitor and optimize container cleanup

Future Enhancements

While our current implementation is production-ready, we're considering additional hardening:

1. seccomp profiles — Fine-grained system call filtering

2. AppArmor/SELinux — Additional kernel-level restrictions

3. RestrictedPython library — More robust namespace restrictions via AST transformation

4. Network namespaces — Custom network policies

5. Resource quotas — Per-user execution limits

Conclusion

Securing code execution requires multiple layers of defense. By combining Docker container isolation, resource limits, and restricted Python namespaces, we've created a system that allows users to run code safely while protecting our infrastructure.

Key takeaways:

1. Never trust user code — Always assume it's malicious

2. Defense in depth — Multiple security layers provide backup protection

3. Test your security — Maintain a comprehensive test suite

4. Monitor and log — Track all executions for security auditing

5. Stay updated — Security is an ongoing process, not a one-time setup

If you're building a platform that executes user code, I hope this post provides a solid foundation for your security architecture.

Resources:

• Docker Security Best Practices

• OWASP Code Injection

• Python Sandboxing Guide

Cyber Code Academy is a modern, gamified platform for mastering Python through interactive challenges, real-time competitions, and AI-powered problem generation. While students focus on solving coding challenges, administrators need robust tools to create, manage, and monitor the platform's content and infrastructure.

In this post, we'll take a deep dive into the admin section, a comprehensive suite of tools that simplifies everything from challenge creation to infrastructure monitoring. We'll explore how we leverage JSON storage, semantic validation, AI-powered generation, translation services, and Docker-based execution to create a scalable and maintainable platform.

The admin dashboard provides a centralized view of all platform operations

Challenge Management: Flexible Test Storage and Semantic Validation

JSON-Based Test Storage

One of the core design decisions in Cyber Code Academy was to store challenge tests as JSON in PostgreSQL's JSONB columns. This approach provides several advantages:

• Flexibility: Tests can have different structures (assertion-based, output-based, or custom validation)

• Queryability: PostgreSQL's JSONB operators allow us to query and filter challenges by test properties

• Versioning: Easy to track changes to test suites over time

• No Schema Migrations: Adding new test types doesn't require database migrations

Each challenge stores its tests in a JSONB array like this:

{
  "tests": [
    {
      "name": "test_basic",
      "code": "assert solve([1, 2, 3]) == 6",
      "hidden": false
    },
    {
      "name": "test_edge_case",
      "code": "assert solve([]) == 0",
      "hidden": true
    }
  ]
}

The database model uses SQLAlchemy's JSONB type to store this flexible structure:

tests = Column(JSONB, nullable=False)  # Array of test objects

The challenge editor shows an UI over JSON structure of tests, making it easy to understand and modify test cases

Semantic Validation: Beyond Test Results

While unit tests verify that code produces correct outputs, they don't ensure that students are learning the intended concepts. A student might solve a challenge using a workaround or unintended approach that passes all tests but misses the educational objective.

This is where semantic validation comes in. We've implemented a two-tier validation system:

AST-Based Validation (Fast & Deterministic)

For challenges that require specific code patterns or structures, we use Python's Abstract Syntax Tree (AST) module to perform fast, deterministic validation. The AST validator can check for:

• Required function definitions

• Prohibited imports or functions

• Required control structures (loops, conditionals)

• Code complexity constraints

• Specific algorithm requirements

The AST validator parses the code into an AST and uses a visitor pattern to check constraints:

class ASTValidator:
    def validate(self, code: str, constraints: Dict[str, Any]) -> ValidationResult:
        tree = ast.parse(code)
        visitor = ASTConstraintVisitor(constraints)
        visitor.visit(tree)
        return ValidationResult(
            passed=len(visitor.errors) == 0,
            errors=visitor.errors,
            warnings=visitor.warnings
        )

This approach is:

• Fast: No API calls, pure Python parsing

• Deterministic: Same code always produces the same result

• Precise: Can detect specific code patterns with high accuracy

Admins can configure semantic validation constraints for each challenge

For admis there is a predefined prompt helping to write a proper AST JSON validator !

LLM-Based Validation (Flexible & Context-Aware)

For challenges where the learning objective is more nuanced, we use Large Language Models (LLMs) to validate that code follows the challenge instructions. The LLM validator:

• Understands the challenge's educational objective

• Checks if the code approach matches the intended learning path

• Provides feedback on code style and best practices

• Detects workarounds that pass tests but miss the point

The LLM validator sends the challenge objective, solution code, and user code to an AI model for analysis:

class LLMValidator:
    async def validate(self, code: str, challenge: Challenge, db: AsyncSession):
        system_prompt = """You are a code validator for a Python learning platform.
        Check if the user's code follows the challenge instructions exactly."""

        user_prompt = f"""Challenge Objective: {challenge.description['objective']}
        Expected Approach: {challenge.solution_code}
        User Code: {code}

        Analyze if the user's code follows the challenge instructions."""

        # Call LLM with automatic usage tracking
        response = await self._call_llm_with_tracking(...)
        return self._parse_response(response)

LLM Fallback Chain: Reliability Through Redundancy

To ensure high availability and handle rate limits, we've implemented a fallback chain across three LLM providers:

1. Groq (Primary): Fast inference with models like llama-3.3-70b-versatile

2. Google Gemini (Fallback): gemini-2.5-flash for reliable performance

3. OpenAI (Last Resort): gpt-4-turbo-preview for maximum quality

The system automatically switches providers when:

• Rate limits are hit (HTTP 429)

• API errors occur

• Timeouts happen

class AIModelManager:
    def handle_error(self, error: Exception, current_model: str):
        if is_rate_limit_error(error):
            self.current_index += 1
            next_model = self.get_next_model()
            return True, next_model, retry_after_seconds
        # ... handle other errors

This multi-provider approach ensures that semantic validation remains available even when individual providers have issues, providing a robust and reliable validation system.

Translation System: Making Challenges Accessible Globally

Creating quality educational content is time-consuming. Translating that content into multiple languages can be prohibitively expensive and slow. To solve this, we've integrated LibreTranslate—an open-source translation service—to automatically translate challenges.

Multi-Language Support with JSONB

Similar to our test storage approach, we use JSONB columns to store translations:

title_i18n = Column(JSONB, nullable=True)  # {"en": "...", "fr": "..."}
description_i18n = Column(JSONB, nullable=True)  # Nested structure
hints_i18n = Column(JSONB, nullable=True)  # Array of translated hints

This structure allows us to:

• Store multiple languages in a single row

• Query by language efficiently

• Add new languages without schema changes

• Maintain translation history

Auto-Translation Workflow

The translation system provides a seamless workflow for admins:

1. Create Challenge in English: Write the challenge with all content in English

2. Auto-Translate: Click a button to translate to target language (e.g., French)

3. Review & Edit: Review the auto-translated content and make manual adjustments

4. Publish: The challenge is now available in both languages

The translation service uses Redis caching to avoid redundant API calls:

class TranslationService:
    async def translate(self, text: str, target_lang: str, source_lang: str):
        # Check Redis cache first
        cache_key = f"translation:{source_lang}:{target_lang}:{hash(text)}"
        cached = await self.redis.get(cache_key)
        if cached:
            return cached.decode('utf-8')

        # Call LibreTranslate API
        translated = await self._call_libretranslate(text, source_lang, target_lang)

        # Cache the result
        await self.redis.setex(cache_key, ttl, translated)
        return translated

This caching strategy:

• Reduces API costs

• Improves response times

• Handles repeated translations (e.g., common phrases)

The translation editor shows side-by-side comparison of original and translated content

Graceful Degradation

The translation system is designed to degrade gracefully:

• If LibreTranslate is unavailable, admins can still manually translate

• Cached translations remain available even if the API is down

• The system logs warnings but doesn't block challenge creation

AI Challenge Generator: From Concept to Complete Challenge

Creating high-quality coding challenges is an art. It requires:

• Clear problem statements

• Appropriate difficulty levels

• Comprehensive test cases

• Engaging narratives (in our case, cyberpunk-themed)

• Validated solutions

To scale challenge creation, we built an AI Challenge Generator that can create complete challenges from simple specifications.

How It Works

The generator takes minimal input:

• Category: e.g., "loops", "functions", "lists"

• Difficulty: "initiate", "hacker", "elite", or "legend"

• Concept: The educational concept to teach

• Context: A cyberpunk narrative theme

• Constraints: Optional special requirements

From this, it generates:

• A complete challenge description with narrative

• Starter code for students

• Solution code with comments

• Comprehensive test suite (visible and hidden tests)

• Hints for struggling students

The Generation Process

1. Prompt Engineering: The system uses carefully crafted prompts that instruct the AI to:

   • Follow the cyberpunk theme

   • Create progressive difficulty

   • Include comprehensive tests

   • Return valid JSON matching our schema

2. Schema Validation: Generated JSON is validated against a JSON Schema to ensure:

   • All required fields are present

   • Data types are correct

   • Structure matches our challenge model

3. Solution Testing: The generated solution code is automatically executed against the generated tests to verify:

   • All tests pass

   • The solution is correct

   • No syntax errors exist

4. Refinement Loop: If tests fail, the system:

   • Sends the error back to the AI

   • Requests corrections

   • Re-validates until tests pass (up to 3 attempts)

async def generate_challenge(self, category, difficulty, concept, context):
    for attempt in range(max_retries):
        # Call AI with model fallback
        response = await self._call_llm(messages, model=current_model)
        challenge_json = self._extract_json(response)

        # Validate schema
        self._validate_schema(challenge_json)

        # Test solution
        test_result = await self._test_solution(challenge_json)
        if not test_result["passed"]:
            # Request correction
            messages.append({"role": "user", "content": refinement_prompt})
            continue

        return challenge_json

Admins can generate complete challenges with just a few inputs

Model Fallback for Reliability

The generator uses the same multi-provider fallback system as semantic validation:

• Tries Groq first (fast and cost-effective)

• Falls back to Gemini if rate limited

• Uses OpenAI as last resort for maximum quality

This ensures challenge generation remains available even during provider outages.

AI Usage Tracking: Understanding Costs and Performance

When using multiple AI providers with different pricing models, understanding usage and costs becomes critical. We've built comprehensive tracking that logs every AI API call.

What We Track

For every AI call, we log:

• Provider & Model: Which service and model was used

• Call Type: Generation, refinement, or validation

• Status: Success, error, or rate limit

• Performance: Response time in milliseconds

• Token Usage: Input tokens, output tokens, total tokens

• Cost Estimation: Estimated cost based on provider pricing

• Rate Limit Info: Retry-after headers and rate limit status

• Metadata: Full response headers, error details, and context

This data is stored in the ai_call_logs table:

class AICallLog(Base):
    provider = Column(String(50), nullable=False, index=True)
    model = Column(String(100), nullable=False, index=True)
    call_type = Column(String(50), nullable=False)
    status = Column(String(20), nullable=False, index=True)
    response_time_ms = Column(Integer, nullable=True)
    input_tokens = Column(Integer, nullable=True)
    output_tokens = Column(Integer, nullable=True)
    total_tokens = Column(Integer, nullable=True)
    cost_estimate = Column(Numeric(10, 6), nullable=True)
    # ... more fields

Usage Dashboard

The admin dashboard provides comprehensive analytics:

• Total Usage: Calls, tokens, and costs over time

• Provider Breakdown: Which providers are used most

• Model Performance: Success rates and response times per model

• Cost Analysis: Spending trends and projections

• Error Tracking: Rate limits, failures, and retry patterns

The AI usage dashboard shows comprehensive statistics on API calls, costs, and performance

Automatic Tracking

Every AI call is automatically tracked without requiring manual instrumentation:

async def _call_llm_with_tracking(self, provider, model, prompts, db):
    # Create call log entry
    call_log = AICallLog(
        provider=provider_name,
        model=model_name,
        status=CallStatus.PENDING.value
    )
    db.add(call_log)
    await db.flush()

    try:
        # Make API call
        response = await provider.generate_text(...)

        # Update with success data
        call_log.status = CallStatus.SUCCESS.value
        call_log.input_tokens = response.usage.input_tokens
        call_log.output_tokens = response.usage.output_tokens
        call_log.cost_estimate = calculate_cost(...)
    except Exception as e:
        # Update with error data
        call_log.status = CallStatus.ERROR.value
        call_log.error_message = str(e)

    return response

This automatic tracking ensures we never miss a call and can accurately analyze costs and performance.

Executor Monitoring: Ensuring Reliable Code Execution

Code execution is the heart of a coding platform. Students submit code, and the system must execute it securely and reliably. We use Docker containers for isolation, and comprehensive monitoring to ensure everything works correctly.

Docker-Based Secure Execution

Each code submission runs in an isolated Docker container with:

• Resource Limits: CPU and memory constraints

• Network Isolation: No external network access

• Timeout Enforcement: Automatic termination of long-running code

• Clean Environment: Fresh container for each execution

The executor service manages a pool of containers to handle concurrent submissions efficiently.

Health Monitoring

The admin section provides real-time monitoring of the executor infrastructure:

• Docker Connection: Is Docker daemon accessible?

• Image Status: Is the executor image present and up-to-date?

• Pool Metrics: Current pool size, active executions, available slots

• Utilization: Percentage of pool capacity in use

Real-time monitoring of executor pool health and status

Execution Statistics

Beyond health checks, the system tracks:

• Total Executions: Number of code runs over time

• Success Rate: Percentage of successful executions

• Average Execution Time: Performance metrics

• User Statistics: Per-user execution patterns

• Challenge Statistics: Which challenges have the most submissions

Debugging Failed Tests

When AI-generated tests fail or students report issues, admins need to debug. The executor monitoring system provides:

• Execution History: View all executions with filters (user, challenge, date range)

• Failed Execution Logs: Full stdout/stderr for failed runs

• Test Results: Detailed test output showing which tests passed/failed

This is particularly valuable for AI-generated challenges. Even after manual review, some edge cases might be missed. The execution logs help identify:

• Test cases that are too strict

• Edge cases not covered by tests

• Performance issues with test execution

• Syntax errors in generated test code

Admins can view detailed logs from failed executions to debug test issues

Example: Debugging an AI-Generated Test

Imagine an AI-generated challenge has a test that's failing unexpectedly:

1. Admin views the challenge in the admin panel

2. Checks execution history for that challenge

3. Finds a failed execution

4. Views the execution logs

5. Sees the test error: AssertionError: Expected [1, 2, 3] but got [1, 2, 3]

6. Realizes the test is comparing lists with == which works, but the error message suggests a different issue

7. Reviews the test code and fixes the assertion

8. Re-tests the challenge

This workflow makes it easy to identify and fix issues in AI-generated content, ensuring quality even when challenges are created automatically.

Conclusion

The admin section of Cyber Code Academy demonstrates how thoughtful tooling can simplify complex platform management. By leveraging:

• JSONB storage for flexible, queryable data structures

• Semantic validation (AST + LLM) to ensure educational quality

• Multi-provider AI fallback for reliability

• Auto-translation to scale content globally

• AI generation to create challenges at scale

• Comprehensive logging to understand costs and performance

• Executor monitoring to ensure reliable code execution

We've created a platform that can scale from a few challenges to thousands, from one language to many, and from manual creation to AI-assisted generation—all while maintaining quality and reliability.

The admin tools don't just make life easier for administrators; they enable the platform to grow and evolve. As we add more challenges, support more languages, and leverage AI more extensively, these tools ensure we can manage complexity without sacrificing quality.

If you've ever deployed a web application, you know the pain: push a small frontend change, wait for the entire platform to restart, and watch your users experience downtime. For the Cyber Code Academy platform, an interactive Python learning platform with real-time competitions, this was the reality. Every deployment meant 2-3 minutes of complete outage, even for the smallest UI tweak.

The culprit? A monolithic Docker Compose setup where every service was tightly coupled. Change the frontend? Restart the database. Update the backend? Restart everything. It was frustrating, inefficient, and frankly, unprofessional.

I decided it was time for a something different and more professional, even for a free test website. I migrated from a single docker-compose.prod.yml file orchestrating everything to a decoupled, three-tier architecture that enables true zero-downtime deployments on Coolify. The result? I can now deploy frontend changes without touching the database, update the backend independently, and keep the infrastructure services running 24/7 (almost 😂)

In this post, I'll walk you through our journey: the problems we faced, the architecture we designed, and how we implemented it. Whether you're running a similar setup or just curious about zero-downtime deployments, I hope this experience helps you avoid the pitfalls I encountered.

The Problem: Monolithic Deployment Pain

Let me start by explaining what we had and why it was problematic.

What is a Monolithic Deployment?

In our original setup, we had a single docker-compose.prod.yml file that defined all our services: PostgreSQL database, Redis cache, LibreTranslate translation service, our FastAPI backend, and our Next.js frontend. When Coolify detected a change (like a new commit to the repository), it would:

1. Stop all containers

2. Rebuild any changed services

3. Start all containers again

4. Wait for health checks to pass

This is what I call a "monolithic deployment"—everything is bundled together, and everything restarts together. It's simple to understand, but it comes with significant drawbacks.

Real-World Impact

The real-world impact was brutal. Here's what happened during a typical deployment:

Scenario 1: Frontend UI Fix

• I push a small CSS fix to improve button styling

• Coolify detects the change and triggers a redeploy

• All services stop: database, Redis, backend, frontend

• Database restarts (unnecessary, but required by the monolith)

• Redis restarts (unnecessary)

• Backend restarts (unnecessary)

• Frontend rebuilds and restarts

• Total downtime: 3-4 minutes

• Users see "Service Unavailable" errors

Scenario 2: Backend API Update

• I add a new endpoint for user profiles

• Same process: everything stops, everything restarts

• Database connections are dropped mid-request

• Active user sessions are lost

• Total downtime: 4-5 minutes

Scenario 3: Infrastructure Change

• I need to update PostgreSQL configuration

• This is the only scenario where a full restart makes sense

• But even here, we're restarting the frontend unnecessarily

Specific Pain Points

Let me break down the specific problems we faced:

1. Database Restarts on Frontend Changes The most frustrating issue: updating a React component would cause our PostgreSQL database to restart. This made no sense—the database had nothing to do with the frontend change. But because everything was in one Docker Compose file, Coolify treated it as one unit.

2. Long Outage Windows Our deployments took 2-5 minutes on average. During this time:

• Users couldn't log in

• Active sessions were lost

• API requests failed

• Real-time features (like our coding battles) disconnected

3. No Independent Updates There was no way to update just the frontend or just the backend. Every change required a full platform restart. This slowed down our development cycle and made us hesitant to deploy small fixes.

4. Resource Waste We were restarting services that didn't need to restart. PostgreSQL, Redis, and LibreTranslate are stable services that rarely change. Restarting them on every deployment was wasteful and risky.

5. Deployment Anxiety Because every deployment meant downtime, we started batching changes. Instead of deploying small fixes immediately, we'd wait until we had multiple changes. This meant bugs stayed in production longer than necessary. Usually to led user play with the pygame, this meant night deployment 😩 Welcome back in the 80s

Understanding the Architecture

Before diving into the solution, let me explain the architecture concepts we're working with. If you're already familiar with microservices and container orchestration, feel free to skip ahead. But I want to make sure everyone understands the "why" behind our decisions.

The Three-Tier Architecture Concept

Instead of one monolithic deployment, we split our platform into three distinct layers, each with different characteristics and update frequencies:

1. Infrastructure Layer: Stable services that rarely change

2. Backend Layer: API application that changes moderately

3. Frontend Layer: User interface that changes frequently

This separation allows us to update each layer independently, which is the key to zero-downtime deployments.

Layer 1: Infrastructure (The Stable Foundation)

The infrastructure layer contains services that form the foundation of our platform. These services are stable, well-tested, and rarely need updates.

PostgreSQL Database

• Stores all application data: users, challenges, submissions, battles

• Rarely changes: maybe a configuration tweak once a quarter

• Critical: if it goes down, the entire platform is unusable

• Resource-intensive: needs consistent memory and CPU

Redis Cache

• Handles session storage and leaderboard caching

• Ephemeral data: can be rebuilt if needed

• Fast: restarts quickly, but still unnecessary to restart on every deployment

• Lightweight: minimal resource usage

LibreTranslate

• Provides automatic translation for our international users

• Pre-loaded models: takes time to start up (60-120 seconds)

• Stable: we update it maybe once a year

• Resource-intensive: loads language models into memory

Executor Builder

• Builds the Docker image used for code execution

• Build-only service: creates an image but doesn't run as a container

• Critical for our code execution features

• Only needs to rebuild when we change security policies or execution environment

Why These Rarely Change These services are infrastructure—they're the foundation, not the application. Think of them like the foundation of a house: you don't rebuild the foundation when you repaint the walls. Similarly, we don't need to restart the database when we update the frontend.

Layer 2: Backend (The Business Logic)

The backend layer contains our FastAPI application—the brain of our platform.

FastAPI Application

• Handles all API logic: authentication, challenge validation, battle management

• Changes frequently: new features, bug fixes, performance improvements

• Depends on Infrastructure: needs database and Redis to function

• Stateless: can be scaled horizontally (run multiple instances)

Key Characteristics

• Updates weekly or bi-weekly as we add features

• Needs to connect to database and Redis (via container names)

• Requires Docker socket access for code execution features

• Has health checks to ensure it's ready before accepting traffic

Why It's Separate The backend changes more frequently than infrastructure but less frequently than the frontend. By separating it, we can:

• Deploy backend updates without touching the database

• Scale backend independently

• Roll back backend changes without affecting infrastructure

Layer 3: Frontend (The User Interface)

The frontend layer contains our Next.js application—what users see and interact with.

Next.js Application

• Serves the user interface: dashboards, challenge browser, battle arena

• Changes most frequently: UI improvements, bug fixes, new pages

• Depends on Backend: makes API calls to the backend

• Stateless: can be scaled horizontally

Key Characteristics

• Updates multiple times per week (sometimes daily)

• Only needs the backend API URL to function

• Builds at deployment time (static assets generated during Docker build)

• Has health checks to ensure it's serving pages correctly

Why It's Separate The frontend changes the most frequently. By separating it:

• We can deploy UI fixes instantly without database restarts

• Users see updates faster

• We can A/B test different frontend versions

• Frontend developers can deploy independently

The Network: How Services Communicate

All three layers communicate over a shared Docker network called cybercodeacademy-proxy. This is crucial for the architecture to work.

Container Name Resolution Docker provides DNS-based service discovery. When services are on the same network, they can find each other by container name:

• Backend finds database at: cybercodeacademy-db

• Backend finds Redis at: cybercodeacademy-redis

• Backend finds translator at: cybercodeacademy-translate

• Frontend finds backend at: configured via environment variable (domain or internal DNS)

Why This Matters Instead of using localhost or IP addresses (which change), we use container names. Docker's internal DNS resolves these names to the correct container IPs, even when containers restart or move to different hosts.

External Network The cybercodeacademy-proxy network is marked as external: true, meaning it exists outside of any single Docker Compose file. This allows:

• Infrastructure services (from docker-compose.infra.yaml) to join the network

• Backend service (from Coolify) to join the network

• Frontend service (from Coolify) to join the network

• All services to communicate with each other

This is the glue that holds our decoupled architecture together.

The Solution: Decoupled Architecture

Now that we understand the architecture, let's dive into how we implemented it. The migration involved three main changes: restructuring our files, configuring Coolify resources, and setting up the network.

Breaking Down the Monolith

The first step was to split our single docker-compose.prod.yml into separate, focused files.

File Structure Changes

Before:

cyber-code-academy/
├── docker-compose.prod.yml    ← Everything in one file
├── backend/
│   └── Dockerfile
└── frontend/
    └── Dockerfile

After:

cyber-code-academy/
├── docker-compose.infra.yaml  ← Infrastructure only
├── docker-compose.dev.yml      ← Local development (full stack)
├── docker-compose.prod.yml     ← DEPRECATED (kept for reference)
├── backend/
│   └── Dockerfile              ← Standalone backend image
└── frontend/
    └── Dockerfile              ← Standalone frontend image

docker-compose.infra.yaml This file contains only the infrastructure services:

• PostgreSQL (cybercodeacademy-db)

• Redis (cybercodeacademy-redis)

• LibreTranslate (cybercodeacademy-translate)

• Executor Builder (builds the executor image)

Here's a simplified version of what it looks like:

services:
  app-db:
    image: postgres:15-alpine
    container_name: my-db
    restart: always
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - cybercodeacademy-proxy
    # ... health checks, resource limits, etc.

  redis:
    image: redis:7-alpine
    container_name: my-redis
    restart: always
    networks:
      - cybercodeacademy-proxy
    # ... configuration

  libretranslate:
    image: libretranslate/libretranslate:latest
    container_name: my-translate
    restart: always
    networks:
      - cybercodeacademy-proxy
    # ... configuration

networks:
  cybercodeacademy-proxy:
    external: true
    name: ${PROXY_NETWORK:-coolify}

Notice that:

• All services use the same external network

• Container names are explicit (for DNS resolution)

• No backend or frontend services—those are deployed separately

Backend Dockerfile The backend Dockerfile remains mostly the same, but we ensure it works with different build contexts:

FROM python:3.13-slim

# Build context can be repository root (.) or backend directory (/backend)
ARG SOURCE_PATH=backend/
ARG REQUIREMENTS_PATH=backend/

WORKDIR /app

# Install dependencies
COPY ${REQUIREMENTS_PATH}requirements.txt ./requirements.txt
RUN pip install --no-cache-dir -r requirements.txt

# Copy application code
COPY --chown=appuser:appgroup ${SOURCE_PATH} /app/

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
    CMD curl -f http://localhost:8000/ || exit 1

# Start application
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Frontend Dockerfile The frontend uses a multi-stage build for optimization:

# Stage 1: Dependencies
FROM node:20-alpine AS deps
WORKDIR /app
COPY frontend/package.json frontend/pnpm-lock.yaml* ./
RUN corepack enable pnpm && pnpm install --frozen-lockfile

# Stage 2: Builder
FROM node:20-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY frontend/ .
ENV NEXT_PUBLIC_API_URL=${PUBLIC_API_URL}
RUN pnpm build

# Stage 3: Runner
FROM node:20-alpine AS runner
WORKDIR /app
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
EXPOSE 3000
CMD ["node", "server.js"]

The key point: both Dockerfiles are designed to work independently, without requiring a full Docker Compose orchestration.

Coolify Configuration

The magic happens in Coolify, where we configure three separate resources.

Resource 1: Infrastructure (Docker Compose)

Type: Docker Compose Purpose: Deploy stable infrastructure services File: docker-compose.infra.yaml

Configuration Steps:

1. Create a new Coolify resource

2. Select "Docker Compose" as the type

3. Upload docker-compose.infra.yaml

4. Set environment variables:

    POSTGRES_USER=pguser
    POSTGRES_PASSWORD=<strong-password>
    POSTGRES_DB=my-db
    PROXY_NETWORK=cybercodeacademy-proxy
    EXECUTOR_IMAGE_NAME=my-executor
   

5. Configure the external network: cybercodeacademy-proxy

6. Deploy

Key Points:

• This resource deploys once and rarely updates

• All infrastructure services run here

• The executor image is built automatically

• Network is external, shared with other resources

Resource 2: Backend (Public Repository)

Type: Public Repository Purpose: Deploy the FastAPI backend independently Repository: mmornati/cyber-code-academyDockerfile: backend/DockerfileBuild Context: /backend (backend directory)

Configuration Steps:

1. Create a new Coolify resource

2. Select "Public Repository"

3. Connect GitHub repository: mmornati/cyber-code-academy

4. Set Dockerfile path: backend/Dockerfile

5. Set build context: /backend

6. Enable auto-redeploy on commits

7. Configure external network: cybercodeacademy-proxy

8. Set environment variables:

    DATABASE_URL=postgresql+asyncpg://pguser:<password>@mydb-db:5432/mydb
    REDIS_URL=redis://my-redis:6379
    JWT_SECRET=<secret>
    JWT_REFRESH_SECRET=<refresh-secret>
    ENVIRONMENT=production
    EXECUTOR_IMAGE_NAME=my-executor
    DOCKER_HOST=unix:///var/run/docker.sock
    LIBRETRANSLATE_URL=http://my-translate:5000
    # ... other variables
   

9. Deploy

Key Points:

• Database URL uses container name (cybercodeacademy-db), not localhost

• Redis URL uses container name (cybercodeacademy-redis)

• Backend can start without executor image (it will build it if missing)

• Health check: / endpoint must return 200 OK

Resource 3: Frontend (Public Repository)

Type: Public Repository Purpose: Deploy the Next.js frontend independently Repository: mmornati/cyber-code-academyDockerfile: frontend/DockerfileBuild Context: / (repository root)

Configuration Steps:

1. Create a new Coolify resource

2. Select "Public Repository"

3. Connect GitHub repository: mmornati/cyber-code-academy

4. Set Dockerfile path: frontend/Dockerfile

5. Set build context: / (repository root)

6. Enable auto-redeploy on commits

7. Configure external network: cybercodeacademy-proxy

8. Set environment variables:

    NEXT_PUBLIC_API_URL=https://api.yourdomain.com
    NEXT_PUBLIC_WS_URL=https://api.yourdomain.com
    NODE_ENV=production
   

9. Configure Traefik routing (if using Coolify's Traefik)

10. Deploy

Key Points:

• Build context is repository root (needed for multi-stage build)

• API URL points to backend's public domain

• Frontend waits for backend to be healthy before starting

• Health check: GET / endpoint must return 200 OK

Network Architecture Deep Dive

The network is the critical piece that makes everything work. Let me explain how we set it up.

Creating the External Network

First, we create the external network on the Coolify server:

docker network create cybercodeacademy-proxy

This network exists independently of any Docker Compose file or Coolify resource. It's persistent and shared.

Connecting Services

Each service connects to this network:

Infrastructure (docker-compose.infra.yaml):

networks:
  cybercodeacademy-proxy:
    external: true
    name: ${PROXY_NETWORK:-coolify}

Backend (Coolify resource):

• In Coolify's network configuration, select "External Network"

• Enter network name: cybercodeacademy-proxy

Frontend (Coolify resource):

• Same as backend: select "External Network"

• Enter network name: cybercodeacademy-proxy

Container Name Resolution

Once services are on the same network, Docker's built-in DNS resolves container names to IP addresses:

• cybercodeacademy-db → PostgreSQL container IP

• cybercodeacademy-redis → Redis container IP

• cybercodeacademy-translate → LibreTranslate container IP

• cybercodeacademy-api → Backend container IP (if you need it)

This is why we use container names in connection strings instead of localhost or IP addresses.

Why External Networks Matter

External networks allow:

• Services from different Docker Compose files to communicate

• Services deployed by different Coolify resources to communicate

• Services to find each other even after restarts (IPs change, names don't)

• Independent deployment without breaking connections

Without external networks, each Docker Compose file or Coolify resource would create its own isolated network, and services couldn't communicate across resources.

Zero-Downtime Deployment: How It Works

Now for the exciting part: how we achieve zero-downtime deployments. The key is Coolify's "Start-before-Stop" strategy combined with health checks.

Understanding Start-before-Stop

Traditional deployments follow a "Stop-then-Start" pattern:

1. Stop old container

2. Build new container

3. Start new container

4. Wait for health checks

5. Result: Downtime during steps 1-4

Start-before-Stop reverses this:

1. Build new container (in parallel with old one running)

2. Start new container

3. Wait for health checks to pass

4. Switch traffic to new container

5. Stop old container

6. Result: Zero downtime (old container serves traffic until new one is ready)

Backend Update Process

Let's walk through what happens when we update the backend:

Step 1: Coolify Detects Change

• We push a commit to the main branch

• Coolify's webhook triggers a new deployment

• Coolify starts building the new backend container

• Old backend container continues serving traffic ✅

Step 2: New Container Starts

• New container is built with the latest code

• New container starts on the cybercodeacademy-proxy network

• New container can see infrastructure services (database, Redis)

• New container begins initialization

• Old backend container still serving traffic ✅

Step 3: Health Checks

• New container runs its health check: curl -f http://localhost:8000/

• Health check passes (container is ready)

• New container is marked as "healthy"

• Old backend container still serving traffic ✅

Step 4: Traffic Switch

• Coolify's load balancer (Traefik) switches traffic to the new container

• New container starts receiving requests

• Old container stops receiving new requests

• No downtime ✅

Step 5: Old Container Stops

• Old container is gracefully stopped

• Connections are closed

• Old container is removed

• New container continues serving traffic ✅

Total Downtime: 0 seconds

Frontend Update Process

The frontend follows the same pattern:

Step 1: Build New Frontend

• Coolify builds new Next.js container

• Build includes static asset generation

• Old frontend still serving pages ✅

Step 2: Start New Container

• New frontend container starts

• Health check: wget --spider http://localhost:3000/

• Old frontend still serving pages ✅

Step 3: Traffic Switch

• Traefik switches traffic to new frontend

• Users see new version immediately

• No downtime ✅

Step 4: Stop Old Container

• Old container stops

• New container continues serving ✅

Total Downtime: 0 seconds

Infrastructure Stability

The beautiful part: infrastructure services never restart during backend or frontend deployments.

During Backend Update:

• PostgreSQL: Running ✅

• Redis: Running ✅

• LibreTranslate: Running ✅

• Backend: Old → New (zero downtime) ✅

During Frontend Update:

• PostgreSQL: Running ✅

• Redis: Running ✅

• LibreTranslate: Running ✅

• Backend: Running ✅

• Frontend: Old → New (zero downtime) ✅

When Infrastructure Updates (rare):

• Only infrastructure services restart

• Backend and frontend continue running (they reconnect automatically)

• Minimal impact (infrastructure updates are infrequent)

Why Health Checks Are Critical

Health checks are what make zero-downtime deployments possible. Without them, Coolify can't know when a container is ready to accept traffic.

Backend Health Check:

HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
    CMD curl -f http://localhost:8000/ || exit 1

This checks:

• Container is running

• Application has started

• Application is responding to HTTP requests

• Database connections are working (implicitly, since the app won't start without DB)

Frontend Health Check:

HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD wget --no-verbose --tries=1 --spider http://127.0.0.1:3000/api/health || exit 1

This checks:

• Container is running

• Next.js server has started

• Pages are being served correctly

What Happens If Health Checks Fail

If health checks fail, Coolify won't switch traffic to the new container. The old container continues serving traffic, and you get a deployment failure notification. This is a safety mechanism—better to have a failed deployment than to serve broken code.

Implementation Details

Now let's get into the nitty-gritty of how we set everything up. I'll walk you through each phase of the deployment process.

Phase 1: Infrastructure Deployment

The infrastructure layer is the foundation, so we deploy it first.

Setting Up the Docker Compose Resource

In Coolify:

1. Navigate to "Resources"

2. Click "New Resource"

3. Select "Docker Compose"

4. Name it: "Infrastructure" or "Database Stack"

Uploading the Compose File

1. Upload docker-compose.infra.yaml

2. Coolify will parse the file and show all services

3. Verify that all services are detected:

   • app-db (PostgreSQL)

   • redis (Redis)

   • libretranslate (LibreTranslate)

   • executor-builder (Executor image builder)

Environment Variables

Set these in Coolify's environment variable section:

POSTGRES_USER=pguser
POSTGRES_PASSWORD=<generate-strong-password>
POSTGRES_DB=my-db
PROXY_NETWORK=cybercodeacademy-proxy
EXECUTOR_IMAGE_NAME=my-executor

Security Note: Use a strong password for PostgreSQL. Generate one with:

openssl rand -base64 32

Network Configuration

Critical Step: Before deploying, create the external network:

# SSH into your Coolify server
docker network create cybercodeacademy-proxy

Then, in Coolify's network settings for this resource:

• Select "External Network"

• Enter: cybercodeacademy-proxy

Volume Management

The infrastructure uses Docker volumes for persistent data:

• postgres_data: PostgreSQL database files

• redis_data: Redis data (optional, Redis can be ephemeral)

Migration Consideration: If you're migrating from the old monolithic setup, you may need to reuse existing volumes. Check your old volumes:

docker volume ls | grep postgres
docker volume ls | grep redis

If you have existing volumes, you can reference them in docker-compose.infra.yaml:

volumes:
  postgres_data:
    external: true
    name: <existing-volume-name>

Deploying

1. Click "Deploy" in Coolify

2. Watch the logs to ensure all services start correctly

3. Verify health checks pass:

   • PostgreSQL: pg_isready should succeed

   • Redis: redis-cli ping should return PONG

   • LibreTranslate: HTTP check should succeed (may take 60-120 seconds)

Verifying the Executor Image

After deployment, verify the executor image was built:

docker images | grep my-executor

You should see: my-executor:latest

If it's missing, the backend will build it automatically on startup, but it's better to have it pre-built.

Phase 2: Backend Deployment

Once infrastructure is running, we deploy the backend.

Creating the Repository Resource

In Coolify:

1. Navigate to "Resources"

2. Click "New Resource"

3. Select "Public Repository"

4. Name it: "Backend API" or "FastAPI Backend"

Connecting GitHub

1. Click "Connect Repository"

2. Authorize Coolify to access your GitHub account

3. Select repository: mmornati/cyber-code-academy

4. Select branch: main (or your production branch)

Dockerfile Configuration

Dockerfile Path: backend/Dockerfile

Build Context: /backend

Why /backend? The backend Dockerfile uses build arguments to handle different contexts:

• Development: context is repository root (.), so it uses backend/ prefix

• Production: context is /backend, so it uses empty prefix (.)

This allows the same Dockerfile to work in both scenarios.

Environment Variables

Set these environment variables in Coolify:

# Database Connection (uses container name, not localhost!)
DATABASE_URL=postgresql+asyncpg://pguser:<password>@my-db:5432/my-db

# Redis Connection (uses container name)
REDIS_URL=redis://cybercodeacadem-redis:6379

# JWT Secrets (generate strong secrets)
JWT_SECRET=<generate-strong-secret>
JWT_REFRESH_SECRET=<generate-strong-secret>

# Application Settings
ENVIRONMENT=production
ADMIN_EMAIL=admin@cybercodeacademy.dev
ADMIN_PASSWORD=<secure-password>

# Executor Configuration
EXECUTOR_IMAGE_NAME=my-executor
EXECUTOR_TIMEOUT_SECONDS=10
EXECUTOR_MEMORY_LIMIT=512m
EXECUTOR_CPU_LIMIT=1.0
EXECUTOR_MAX_POOL_SIZE=5

# Docker Socket (for executor container management)
DOCKER_HOST=unix:///var/run/docker.sock

# AI Provider
AI_PROVIDER=google
GOOGLE_GENAI_API_KEY=<your-google-ai-key>

# Translation Service (uses container name)
LIBRETRANSLATE_URL=http://my-translate:5000

Critical Points:

• DATABASE_URL uses cybercodeacadem-db (container name), not localhost or an IP

• REDIS_URL uses cybercodeacadem-redis (container name)

• LIBRETRANSLATE_URL uses cybercodeacadem-translate (container name)

• All secrets should be strong and unique

Network Configuration

1. In Coolify's network settings for the backend resource

2. Select "External Network"

3. Enter: cybercodeacadem-proxy

This connects the backend to the same network as infrastructure services.

Docker Socket Access

The backend needs access to the Docker socket to manage executor containers. In Coolify:

1. Enable "Docker Socket" or "Privileged Mode"

2. This mounts /var/run/docker.sock into the container

3. Allows the backend to create/stop executor containers for code execution

Security Note: Docker socket access is powerful. Ensure your backend code is secure and doesn't allow arbitrary container creation.

Auto-Redeploy Configuration

Enable auto-redeploy:

1. In Coolify, go to the backend resource settings

2. Enable "Auto Deploy on Push"

3. Select the branch: main (or your production branch)

4. Coolify will automatically deploy when you push to this branch

Health Check Configuration

Coolify will use the health check defined in the Dockerfile:

HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
    CMD curl -f http://localhost:8000/ || exit 1

Ensure your backend has a root endpoint (/) that returns 200 OK. This is what the health check calls.

Deploying

1. Click "Deploy" in Coolify

2. Watch the build logs

3. Once built, the container starts

4. Health checks run

5. Once healthy, the backend is ready

Verifying Backend Connectivity

After deployment, verify the backend can connect to infrastructure:

# Check backend logs
docker logs cybercodeacadem-api

# Look for:
# - "Connected to database"
# - "Redis connection established"
# - "Application startup complete"

If you see connection errors, check:

• Network configuration (all services on same network?)

• Container names (match exactly?)

• Environment variables (correct passwords/secrets?)

Phase 3: Frontend Deployment

Finally, we deploy the frontend.

Creating the Repository Resource

1. Navigate to "Resources"

2. Click "New Resource"

3. Select "Public Repository"

4. Name it: "Frontend Web" or "Next.js Frontend"

Connecting GitHub

Same as backend:

1. Connect repository: mmornati/cyber-code-academy

2. Select branch: main

Dockerfile Configuration

Dockerfile Path: frontend/Dockerfile

Build Context: / (repository root)

Why repository root? The frontend Dockerfile needs access to:

• frontend/ directory (source code)

• user-docs/ directory (documentation to build)

• Root-level files if needed

Using repository root as build context allows the Dockerfile to copy from multiple directories.

Environment Variables

Set these in Coolify:

NEXT_PUBLIC_API_URL=https://api.yourdomain.com
NEXT_PUBLIC_WS_URL=https://api.yourdomain.com
NODE_ENV=production

Important:

• NEXT_PUBLIC_* variables are embedded at build time, not runtime

• They must be set before building the Docker image

• If you change them, you must rebuild the frontend

API URL Options:

• Public Domain: https://api.yourdomain.com (if backend has public domain)

• Internal DNS: http://my-api:8000 (if using internal network, but this won't work for browser requests)

• Coolify Proxy: Use Coolify's internal proxy if configured

For browser requests, you typically need a public domain. The frontend runs in the user's browser, so it can't use Docker's internal DNS.

Network Configuration

1. Select "External Network"

2. Enter: cybercodeacadem-proxy

Even though the frontend doesn't directly connect to infrastructure services, being on the same network can be useful for:

• Health checks

• Internal monitoring

• Future features that might need direct access

Traefik Routing (Optional)

If using Coolify's Traefik for routing:

1. Enable "Traefik" in frontend resource settings

2. Set domain: yourdomain.com

3. Traefik will automatically:

   • Generate SSL certificates (Let's Encrypt)

   • Route traffic to the frontend container

   • Handle load balancing

Health Check

The frontend health check:

HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD wget --no-verbose --tries=1 --spider http://127.0.0.1:3000/api/health || exit 1

Ensure your Next.js app has a /api/health endpoint that returns 200 OK.

Deploying

1. Click "Deploy"

2. Build process may take 5-10 minutes (Next.js builds can be slow)

3. Once built, container starts

4. Health checks run

5. Frontend is ready

Verifying Frontend Connectivity

After deployment:

1. Open your domain in a browser

2. Check browser console for API errors

3. Verify frontend can reach backend API

4. Test a few key features (login, challenge loading, etc.)

Key Configuration Details

Let me cover some important configuration details that apply to all services.

Container Naming Conventions

We use explicit container names for DNS resolution:

• cybercodeacadem-db (PostgreSQL)

• cybercodeacadem-redis (Redis)

• cybercodeacadem-translate (LibreTranslate)

• cybercodeacadem-api (Backend)

• cybercodeacadem-web (Frontend)

Why explicit names?

• Predictable DNS resolution

• Easy to reference in connection strings

• Consistent across deployments

• No dependency on Docker Compose service names

Health Check Strategies

Infrastructure Services:

• PostgreSQL: pg_isready command

• Redis: redis-cli ping

• LibreTranslate: HTTP request to /

Application Services:

• Backend: HTTP GET to /

• Frontend: HTTP GET to /api/health

Best Practices:

• Health checks should be lightweight (fast)

• They should verify the service is actually working, not just running

• Use appropriate intervals (30s is good for most services)

• Set reasonable timeouts (10s is usually enough)

Resource Limits

We set resource limits to prevent any single service from consuming all resources:

PostgreSQL:

deploy:
  resources:
    limits:
      memory: 512M
    reservations:
      memory: 256M

Redis:

deploy:
  resources:
    limits:
      memory: 256M
    reservations:
      memory: 64M

Backend:

• Memory limit: 1G

• CPU limit: 2.0 (if needed)

Frontend:

• Memory limit: 512M

• CPU limit: 1.0 (if needed)

These limits ensure fair resource allocation and prevent one service from starving others.

Benefits & Results

Now that we've covered the implementation, let's talk about the results. The migration has transformed how we deploy and operate our platform.

Operational Benefits

Zero-Downtime Deployments The most obvious benefit: we can now deploy without any user-visible downtime. Frontend updates, backend updates, and even some infrastructure changes happen seamlessly. Users never see "Service Unavailable" errors during deployments.

Before: 3-5 minutes of downtime per deployment After: 0 seconds of downtime

Independent Scaling We can scale services independently based on their needs:

• Frontend: Scale up during peak traffic (more users browsing)

• Backend: Scale up during battle events (more API calls)

• Infrastructure: Keep stable (rarely needs scaling)

This wasn't possible with the monolithic setup—we had to scale everything together.

Faster Iteration Cycles Because deployments are risk-free (no downtime), we deploy more frequently:

• Before: 1-2 deployments per week (batched changes)

• After: 5-10 deployments per week (deploy as soon as code is ready)

This means:

• Bugs are fixed faster

• Features reach users sooner

• We can experiment with confidence

Better Resource Utilization We're no longer wasting resources restarting services that don't need to restart:

• Database stays running (saves 30-60 seconds per deployment)

• Redis stays running (saves 10-20 seconds)

• LibreTranslate stays running (saves 60-120 seconds)

Over a month, this adds up to significant time and resource savings.

Developer Experience

Deploy Frontend Without Touching Database This is the game-changer. Frontend developers can now deploy UI changes without worrying about database restarts. A CSS fix? Deploy in 2 minutes, zero impact on backend or database.

Quick Rollbacks If a deployment goes wrong, we can roll back just the affected service:

• Frontend broken? Roll back frontend only (30 seconds)

• Backend broken? Roll back backend only (1 minute)

• Infrastructure issue? Rare, but can be addressed independently

With the monolithic setup, any rollback required restarting everything (5+ minutes).

Parallel Development Different teams can work on different services without blocking each other:

• Frontend team deploys UI improvements

• Backend team deploys API changes

• Both happen simultaneously, no conflicts

Confidence in Deployments Knowing that deployments won't cause downtime gives us confidence to:

• Deploy on Fridays (no more "no deployments on Fridays" rule)

• Deploy during business hours (users won't notice)

• Experiment with new features (easy to roll back if needed)

Cost & Performance

Reduced Unnecessary Restarts Every unnecessary restart consumes:

• CPU cycles (container initialization)

• Memory (loading services into RAM)

• I/O bandwidth (reading files, connecting to databases)

• Time (waiting for services to start)

By eliminating unnecessary restarts, we:

• Reduce server load

• Lower resource costs

• Improve overall system stability

Better Resource Allocation With independent services, we can:

• Allocate more resources to services that need them

• Scale down services that don't need resources

• Optimize each service independently

For example:

• Frontend: Lightweight, can run on smaller instances

• Backend: More CPU-intensive, needs more resources

• Database: Memory-intensive, needs dedicated resources

Improved Reliability The decoupled architecture is more resilient:

• If frontend fails, backend and database keep running

• If backend fails, database keeps running (data is safe)

• If one service has issues, others are unaffected

This isolation prevents cascading failures.

Real-World Example

Let me share a real example from our platform:

Scenario: We discovered a UI bug where the challenge browser wasn't showing difficulty badges correctly. It was a simple CSS issue—one line of code.

Before (Monolithic):

1. Fix the CSS (5 minutes)

2. Wait until low-traffic period (2 hours later)

3. Deploy (triggers full restart)

4. 4 minutes of downtime

5. Users see "Service Unavailable"

6. Total time: 2+ hours, 4 minutes of downtime

After (Decoupled):

1. Fix the CSS (5 minutes)

2. Push to main branch

3. Coolify auto-deploys frontend (2 minutes)

4. Zero downtime

5. Users see the fix immediately

6. Total time: 7 minutes, 0 seconds of downtime

This is the difference decoupling makes.

Lessons Learned & Best Practices

After going through this migration, I've learned a lot. Here are the key lessons and best practices I'd recommend to anyone considering a similar migration.

What Worked Well

1. External Networks Are Your Friend Using an external network (cybercodeacadem-proxy) was the key to making everything work. It allows services from different Coolify resources to communicate seamlessly. Without it, we'd be stuck with complex networking workarounds.

2. Container Names for DNS Using explicit container names (cybercodeacadem-db, cybercodeacadem-redis) instead of service names or IPs made connection strings predictable and reliable. Docker's DNS resolution is rock-solid when you use container names.

3. Health Checks Are Non-Negotiable Health checks are what make zero-downtime deployments possible. Without them, Coolify can't know when a container is ready. Invest time in getting health checks right—they're worth it.

4. Build Context Matters Understanding Docker build contexts was crucial. The backend uses /backend as context, while the frontend uses / (repository root). Getting this wrong causes confusing build errors.

5. Gradual Migration We didn't migrate everything at once. We:

1. Set up infrastructure first

2. Migrated backend second

3. Migrated frontend last

This gradual approach let us test each piece independently and catch issues early.

Challenges Encountered

1. Network Configuration Confusion Initially, we had issues with services not finding each other. The problem: we were mixing localhost, IP addresses, and container names. The solution: use container names consistently, and ensure all services are on the same external network.

2. Environment Variable Timing Frontend environment variables (NEXT_PUBLIC_*) are embedded at build time, not runtime. We learned this the hard way when changing API URLs didn't work until we rebuilt the image. The lesson: set environment variables before building, not after.

3. Volume Migration Migrating existing PostgreSQL and Redis volumes was tricky. We had to:

• Identify existing volumes

• Reference them in the new compose file

• Ensure permissions were correct

For new deployments, this isn't an issue, but for migrations, it's something to plan for.

4. Executor Image Building The executor image builder service in docker-compose.infra.yaml doesn't run as a container—it only builds the image. Coolify initially didn't build it automatically. We worked around this by having the backend build it on startup if missing, but it's better to pre-build it.

5. Health Check Endpoints Not all services had proper health check endpoints initially. We had to add:

• Backend: / endpoint that returns 200 OK

• Frontend: /api/health endpoint

This is easy to fix, but it's something to plan for.

Recommendations for Others

When to Use This Pattern

This decoupled architecture pattern is ideal when:

• ✅ You have services with different update frequencies (stable infrastructure, frequently-changing applications)

• ✅ You need zero-downtime deployments

• ✅ You're using a platform like Coolify that supports independent resource deployment

• ✅ You have a monorepo with multiple applications

• ✅ You want to scale services independently

When NOT to Use This Pattern

This pattern might be overkill if:

• ❌ You have a simple single-application setup

• ❌ All your services change together (true monolith)

• ❌ You don't have deployment downtime issues

• ❌ Your deployment platform doesn't support independent resources

Network Configuration Tips

1. Create the external network first: Before deploying anything, create the network:

    docker network create <network-name>
   

2. Use consistent naming: Use the same network name across all resources. We use cybercodeacademy-proxy everywhere.

3. Verify network connectivity: After deploying, verify services can reach each other:

    docker exec -it <container-name> ping <other-container-name>
   

4. Document container names: Keep a list of container names and what they're used for. This helps when configuring connection strings.

Health Check Best Practices

1. Make health checks meaningful: Don't just check if the process is running—check if the service is actually working. For example:

   • Database: Can it accept connections?

   • Backend: Can it respond to HTTP requests?

   • Frontend: Can it serve pages?

2. Set appropriate intervals:

   • Fast services (Redis): 10s interval

   • Medium services (Backend): 30s interval

   • Slow services (LibreTranslate): 30s interval with longer start period

3. Use timeouts wisely: Health checks should fail fast if the service is broken, but give enough time for slow-starting services.

4. Test health checks locally: Before deploying, test health checks in your local environment to ensure they work correctly.

Volume Management Considerations

1. Plan for volume migration: If you're migrating from a monolithic setup, identify existing volumes and plan how to reference them.

2. Use named volumes: Named volumes are easier to manage than anonymous volumes. They're also easier to backup and migrate.

3. Backup before migration: Always backup volumes before making changes. PostgreSQL and Redis data is critical—don't risk losing it.

4. Consider volume drivers: For production, consider using volume drivers (like NFS or cloud storage) for better reliability and portability.

General Best Practices

1. Start with infrastructure: Deploy infrastructure services first. They're the foundation, and other services depend on them.

2. Test each layer independently: Don't deploy everything at once. Test each layer (infrastructure, backend, frontend) independently before moving to the next.

3. Monitor during migration: Watch logs, metrics, and health checks during migration. Catch issues early.

4. Have a rollback plan: Know how to roll back each service independently. Practice rollbacks in a staging environment.

5. Document everything: Document container names, network names, environment variables, and connection strings. This helps when troubleshooting and onboarding new team members.

6. Use version control: Keep all configuration files (Dockerfiles, docker-compose files) in version control. This makes it easy to track changes and roll back if needed.

Conclusion

Migrating from a monolithic Docker Compose deployment to a decoupled, three-tier architecture was one of the best decisions we made for Cyber Code Academy. The benefits are clear: zero-downtime deployments, independent scaling, faster iteration, and better resource utilization.

The journey wasn't without challenges—network configuration, health checks, and volume migration required careful planning. But the result is a deployment system that's robust, flexible, and professional.

If you're facing similar deployment pain, I encourage you to consider this approach. Start small: separate your infrastructure from your applications. Then, as you gain confidence, further decouple your services. The investment in time and effort pays off in reduced downtime, faster deployments, and happier users.

The key takeaway: deployment architecture matters. A well-designed deployment system enables rapid iteration, confident releases, and reliable operations. Don't let a monolithic deployment hold you back.

For us, this migration was transformative. We went from dreading deployments to deploying with confidence multiple times per week. Our users never see downtime, our developers can iterate quickly, and our platform is more resilient than ever.

If you're interested in seeing the actual configuration files or have questions about the migration, check out our repository or reach out. I'm happy to share more details about our setup.

Here's to zero-downtime deployments! 🚀

Resources:

• Coolify Documentation

• Docker Networking Guide

• Docker Compose External Networks

That got me thinking: what if I built something that could help him (and other teenagers) learn Python in a fun, interactive way? Something that feels more like a game than homework. So I did just that.

What I Built

I created Cyber Code Academy - an interactive Python learning platform where students can solve challenges, compete in real-time battles, and learn through gamified experiences. It features:

• 100+ Python challenges from beginner to expert level

• Real-time competitive battles against other learners

• AI-powered problem generation

• Built-in code editor with instant execution in the browser

• Progress tracking with XP, levels, and leaderboards

• Achievement badges and learning paths

Tech stack: Next.js 14, FastAPI, PostgreSQL, Redis, and Docker for isolated code execution.

You can try it out here: https://play.pygame.ovh/

The "Pure Vibe Coding" Approach

Here's where it gets interesting. I built this entire project using what I call "pure vibe coding" - working entirely with Cursor and GitHub Copilot. No rigid planning, no extensive documentation upfront. Just flow, intuition, and AI assistance.

The result? A fully functional platform that went from idea to production faster than I ever thought possible (5 days). The AI tools didn't just help with code - they accelerated every aspect of development: stack and libs choice, bug fixing, testing, ...

But here's the kicker: even the documentation was fully AI-generated. Every page, every section, every explanation - and yes, even the screenshots - were created by AI. Check it out: https://play.pygame.ovh/docs/index.html

It's a complete end-to-end AI-assisted development story: code, documentation, and visuals. In a future post, I'll dive deeper into the actual workflow and methodology behind this approach (because let's be honest, "pure vibe" sounds cool but there's definitely a method to the madness).

Who Is This For?

Primarily, I built this for teenagers like my son who are learning Python at school. But honestly? It's for anyone who wants to learn or practice Python. It's completely free, no strings attached.

It's designed as a simple "game" to learn code interactively. No personal data collected - just a username (and who cares about that, right? :P). The focus is purely on learning and having fun while doing it.

Why Python? Because that's what French schools are teaching now. No idea why this choice, but here we are. Python it is!

A Security Experiment

One of the most fascinating things I noticed during development: security seemed to be auto-managed even when I didn't explicitly specify it. The AI tools, combined with modern frameworks and best practices, naturally implemented security measures I hadn't consciously planned for.

This got me curious. So here's an open invitation to the skilled developers and security researchers out there: try to hack it. Seriously. Give it your best shot, and then tell me:

• How you did it

• What happened

• What you found

I'm genuinely interested in understanding how security emerged organically in this "pure vibe" approach. It's a learning opportunity for all of us.

What's Next?

The code exists on GitHub, but I haven't published it yet. I want to clean it up first, make it more presentable. But if there's interest, I'm happy to share it. I'm also open to feedback.

This is meant to be a community project - a tool for learning, built with modern AI assistance, and open to improvement.

Try It Out

Head over to https://play.pygame.ovh/ and give it a spin. Whether you're a teenager learning Python, a developer looking to practice, or someone curious about what "pure vibe coding" can produce - you're welcome.

Share your feedback, report bugs, suggest features. And if you're one of those skilled hackers I mentioned earlier? Well, you know what to do. 😉

P.S. - For those interested in the technical details and workflow behind this "pure vibe coding" approach, stay tuned. I'll be sharing a more detailed post on the methodology soon.

Why This Automation?

Hitachi recently significantly changed their approach to connecting wireless modules to their devices. These changes, while aimed at simplifying their ecosystem, introduced new challenges for smart home enthusiasts:

• Simplified Hardware: Hitachi transitioned from requiring two expensive modules for wireless connectivity to a single, more cost-effective module.

  

• Limited Connectivity Options: The new module is designed to connect exclusively through the official application and website, removing previously available options like APIs or Modbus.

• Discovering the Solution: An analysis of how the official website communicates with the devices identified a list of URLs containing the necessary information to control the devices. This discovery became the foundation for building this custom automation.

This integration bridges the gap by leveraging these insights, enabling seamless control of Hitachi devices within the Home Assistant ecosystem.

NOTE: As I own only a Hitachi Yutaki Head Pump, I don’t know how the integration can fit with the other brand devices.

Key Features of the Integration

This custom integration, available on GitHub, brings powerful capabilities to your smart home setup, including:

• Device Support: Seamlessly integrates with Hitachi appliances using the CS-Net communication protocol.

• Real-Time Monitoring: View status updates and diagnostics directly within Home Assistant.

• Full Control: Adjust device parameters such as temperature, mode, and power state remotely.

• Automation-Ready: Leverage Home Assistant’s automation engine to create rules and triggers based on device activity.

How It Works

This integration leverages the CS-Net protocol to communicate with supported Hitachi devices. Once installed, it establishes a connection between Home Assistant and your appliances, enabling bidirectional communication for control and status updates. The setup process is straightforward and requires minimal technical expertise.
It uses the provided CSNet Home credentials to enable the communication and, when errors occur it re-authenticate the integration. There is so far not a better or proper way to interact with it.

Step-by-Step Guide to Installation

Here’s how to get started:

1. Download the Integration: Add the integration repository to the HACS Custom repositories.

2. Install: Install the integration by looking for “csnet” or “hitachi” in the list of hacs available integration.

3. Restart Home Assistant: Reload your instance to activate the integration.

4. Add the new Integration: going to the “Devices” section and add the new integration (looking with the same kind of filters used to find it in HACS)

5. Configure: The installation process will ask in the UI for your credentials and, everything goes fine it will display the found climate devices asking for their location.

For detailed steps, troubleshooting tips, and additional configuration options, refer to the documentation on GitHub.

Real-World Use Cases

This integration opens the door to numerous possibilities:

• Energy Savings: Automate your Hitachi air conditioner to maintain optimal temperatures during peak hours and reduce usage when not needed.

• Comfort Automation: Pair your Hitachi devices with motion sensors to adjust settings based on room occupancy.

• Unified Ecosystem: Integrate your Hitachi appliances with other smart devices, such as thermostats, lights, and voice assistants, for seamless control.

What’s Next?

This is just the beginning. Future updates will include:

• Expanded Device Support: Adding compatibility with more Hitachi products.

• Community Contributions: Welcoming feedback, bug reports, and feature requests from the Home Assistant community.

Conclusion

This custom integration for Home Assistant empowers users to unlock the full potential of their Hitachi devices, bringing them into the modern smart home ecosystem. With enhanced control, energy savings, and comfort at your fingertips, it’s time to take your home automation to the next level.

Ready to get started? Visit the GitHub repository to download the integration, and don’t forget to share your experience and feedback. Let’s build a smarter, more connected future together!

Introduction

In France, many homes are now equipped with the Everblue water meter. Water companies favor these devices because they facilitate remote readings, bypassing the need for physical access to properties, which can be challenging if homeowners are unavailable. What makes Everblue particularly interesting is its connectivity feature, which allows technicians to access water usage data wirelessly, avoiding incorrect billing due to missed readings. However, one must note that due to regulatory limits on wireless transmissions, these devices only operate during working hours on weekdays.

Why Integrate Everblue with Home Assistant?

As someone who enjoys automating every possible aspect of my home, integrating Everblue with Home Assistant allows me to monitor and control water usage meticulously. This setup helps answer questions like, "How much water does a shower use?" or "What’s the consumption when running the washing machine?" By incorporating Everblue into the Home Assistant energy dashboard, you can track these metrics over time, optimizing your water usage and understanding your consumption patterns. For this project, you will need:

• A Raspberry Pi (any model will do; I used an old RPi Rev B)

• A CC1101 wireless module, which operates at the 433Mhz frequency—commonly used in various household devices

This journey began with decrypting the communication protocol of the Everblue meter, thanks to a group of French enthusiasts who laid the groundwork. You can explore their original research here (note: the content is in French). Several subsequent projects have built on this, utilizing platforms like Raspberry Pi, ESP8266, and ESP32.

Step-by-Step Integration Process

After experimenting with different versions, I settled on a Raspberry Pi-based fork that best suited my goals. The process is straightforward if you follow the instructions outlined in the GitHub project readme:

1. Enable SPI via raspi-config.

2. Install WiringPi and libmosquitto-dev.

3. Configure meter and MQTT settings in the code.

4. Compile and run the code to start receiving data.

5. Set up a crontab to automate the reading process once a day.

Make sure to adjust the device frequency as necessary, as slight deviations from the standard 433Mhz are possible. If the device is not initially detected, you may need to attempt multiple scans.

./everblu_meters 0

If at the end of scan process the reported frequency is 0, this means device was not found. You may have to test several time before to have the device working frequency. When working you will have a message like the following one:

{ 
    "date":"Sat Jul 15 13:06:04 2023", 
    "frequency":"433.8000", 
    "min":"433.7900", 
    "max":"433.8100"
}

Once everything is well configured you can complete scheduling the EverBlue meter read once per day to prevent the device battery drain and, remember: working hours only!

On my side I create a simple crontab:

crontab -e

With the following content:

0 10 * * 1-5 /home/mmornati/everblu-meters-pi/everblu_meters 433.7560 >> /tmp/everblu.log 2>&1

This will be executed every week day at 10 a.m. and writing execution logs in the /tmp/everblu.log file let me check if everything is ok.

The file content

CC1101 Verion : 0x0014
CC1101 found OK!
Base MQTT topic is now everblu/cyble-23-0199454-pi
Connected to MQTT broker (almost)
Trying to query Cyble at 433.7560MHz
Reading data...MQTT : Subscribed OK (mid: 1): 2
Consumption   : 222583 Liters
Battery left  : 166 Months
Read counter  : 160 times
Working hours : from 06H to 18H
Local Time    : Fri Apr 26 10:00:09 2024
RSSI  /  LQI  : -48dBm  /  -128
CC1101 Verion : 0x0014
CC1101 found OK!
Base MQTT topic is now everblu/cyble-23-0199454-pi
Connected to MQTT broker (almost)
Trying to query Cyble at 433.7560MHz
Reading data...MQTT : Subscribed OK (mid: 1): 2
Consumption   : 223486 Liters
Battery left  : 166 Months
Read counter  : 161 times
Working hours : from 06H to 18H
Local Time    : Mon Apr 29 10:00:09 2024
RSSI  /  LQI  : -48dBm  /  -128

The interesting thing in the information returned by the everblue meter you have the working hours of your device helping you for the schedule `from 06H to 18H`

Displaying Information in Home Assistant

The final step involves creating sensors within Home Assistant to display the data from the MQTT topics:

sensor:
  - name: "water_meter_consumption"
    state_topic: "everblu/cyble-23-0199454-pi/json"
    unique_id: "water_meter_consumption"
    value_template: "{{ value_json.liters }}"
    unit_of_measurement: "L"
    device_class: water
    state_class: total_increasing
  - name: "water_meter_last_read"
    state_topic: "everblu/cyble-23-0199454-pi/json"
    unique_id: "water_meter_last_read"
    value_template: "{{ value_json.ts }}"
    device_class: timestamp

These sensors will now appear in your Energy Dashboard, allowing you to monitor water usage effectively.

Common Issues

Occasionally, the script may fail to detect the Everblue meter. I’ve modified the script to retry several times before giving up, which resolves the issue most of the time. If problems persist, they're usually resolved the following day.

Replace the line 323 with the following code:

int i=0; 
do { 
    printf("Reading data..."); 
    meter_data = get_meter_data(); 
    i++; 
    sleep(5); 
} while (i<10 && !meter_data.ok);

Conclusion

While the journey to integrate the Everblue meter with Home Assistant was fraught with challenges, particularly with the initial ESP32 attempts, the final setup using a Raspberry Pi proved successful. This integration not only enhances my understanding of household water consumption but also demonstrates the power of home automation in managing resources efficiently.

I hope this guide helps you streamline your own smart water meter integration. If you encounter any issues or have questions, feel free to reach out or comment below.

What do you need?

• A smart bulb (or equivalent to control a bulb)

• A smart motion sensor

• A input_boolean to check the way the light is powered on

Input Boolean

Nothing special here, you just need to put it within your input_boolean.yaml file or directly in the configuration.yaml, depending on how you are managing your HassIO configuration.
To simplify my global configuration, on my side I put this within the global configuration file: input_boolean: !include components/input_boolean.yaml

input_boolean: !include components/input_boolean.yaml

Which then allows you to put all your booleans configurations within the defined file.

A different way to include external files, which I'm using with automation, is to put a folder instead of a file and ask Home Assistant to merge everything to get the final configuration:automation: !include_dir_merge_list automations/

automation: !include_dir_merge_list automations/

This allows your automation folder to put 1 YAML per automation and so separate it to simplify the management.

Anyway, getting back to our boolean. What you have to put inside the external file is:

terrasse_salon_auto_on:
  name: Terrasse Salon Motion ON
  icon: mdi:lightbulb

This will create an input_boolean named terrasse_salon_auto_on we will use later in our automation.

The Automation

We have two different automation to control the power-on and the power-off.

- alias: Terrasse Salon ON
  id: terrasse_salon_on
  trigger:
    platform: state
    entity_id: binary_sensor.motion_salon_occupancy
    to: "on"
  condition:
    - condition: state
      entity_id: light.terrasse_salon
      state: "off"
    - condition: numeric_state
      entity_id: sensor.motion_salon_illuminance_lux
      below: 50
    - condition: state
      entity_id: input_boolean.terrasse_motion_sensor_enabled
      state: "on"
  action:
    - service: light.turn_on
      entity_id: light.terrasse_salon
    - service: input_boolean.turn_on
      entity_id: input_boolean.terrasse_salon_auto_on

- alias: Terrasse Salon OFF
  id: terrasse_salon_off
  trigger:
    platform: state
    entity_id: binary_sensor.motion_salon_occupancy
    to: "off"
    for:
      minutes: 2
  condition:
    - condition: state
      entity_id: light.terrasse_salon
      state: "on"
    - condition: or
      conditions:
        - condition: state
          entity_id: input_boolean.terrasse_salon_auto_on
          state: "on"
        - condition: state
          entity_id: input_boolean.ignore_light_manual_on
          state: "on"
  action:
    - service: light.turn_off
      entity_id: light.terrasse_salon
    - service: input_boolean.turn_off
      entity_id: input_boolean.terrasse_salon_auto_on

As usual, we will enter each part of the script to understand what it does.

The Trigger

We want to turn on and off the light bulb when motion is detected. So we will use a state trigger on this particular sensor.

trigger:
    platform: state
    entity_id: binary_sensor.motion_salon_occupancy
    to: "on"

When the occupancy sensor of the motion sensor is moving to on the script is triggered.

For the off part, we improve a little bit the trigger to prevent the light from flickering all the time if we are outside but not always moving or not always in front of the motion sensor.

trigger:
    platform: state
    entity_id: binary_sensor.motion_salon_occupancy
    to: "off"
    for:
      minutes: 2

The for minutes is doing the job: if the occupancy is off for at least 2 minutes, the action is triggered.

The Conditions

If there is motion, when do we want to power on the light? If it is dark and if, for sure, the light is off. So, this is mainly what we find:

condition:
    - condition: state
      entity_id: light.terrasse_salon
      state: "off"
    - condition: numeric_state
      entity_id: sensor.motion_salon_illuminance_lux
      below: 50
    - condition: state
      entity_id: input_boolean.terrasse_motion_sensor_enabled
      state: "on"

• The state part is checking if the light is off

• The numeric_state is validated by the illuminance value provided by the motion sensor. Which value to put here? Just made some tests. 0 should be a good value (no light at all) but I preferred to move a little bit up to have the power bulb powered on with low illuminance.

• The last state is another input_boolean I added to be able to completely prevent light from being powered on. I'm using this during the night: if the night alarm is on, this means nobody will go outside, so I don't want to have the lights powered on by movements.

For the power-off action, there is something similar, but it is here we will use the added input boolean to do the magic.

  condition:
    - condition: state
      entity_id: light.terrasse_salon
      state: "on"
    - condition: or
      conditions:
        - condition: state
          entity_id: input_boolean.terrasse_salon_auto_on
          state: "on"
        - condition: state
          entity_id: input_boolean.ignore_light_manual_on
          state: "on"

• The state of the light. It sure must be on

• The state input_boolean we previously configured. We will power off the light bulb if it was automatically turned on (we will see in a while when this flag will be turned on). This means if we power on the light with the home assistant application or if a switch, the flag should be false and the light won't be turned off.

• Here you will see a or condition with a second input_boolean.ignore_light_manual_on. I'm using it to disable the previous flag: If I want to turn off anyway the light, never mind how it was turned on.

The Action

If everything is validated the light should be turned on or off, depending on the automation we are considering, but not only: we will control the input_boolean at this level.

  action:
    - service: light.turn_on
      entity_id: light.terrasse_salon
    - service: input_boolean.turn_on
      entity_id: input_boolean.terrasse_salon_auto_on

You can see in the turn-on script, two services are fired: one for the light itself and the second one to move the boolean to true. This means if the light is turned on by the automation, the boolean contains the value to check this.
It is in my opinion the simple way to control this, but you can check in many other ways.

On the power-off part, it is exactly the opposite: we move the flag to false to get back to the initial state.

  action:
    - service: light.turn_off
      entity_id: light.terrasse_salon
    - service: input_boolean.turn_off
      entity_id: input_boolean.terrasse_salon_auto_on

What do you need for this?
* Automatic / Home Assistant controller Covers
* One (or more) temperature sensors
* and for sure, one or more windows exposed to the sunlight 😉

The Trigger

As I already described for the presence simulation script, the trigger is a time_pattern because I want to constantly recheck during a specific time frame if conditions are met.
An alternative, to reduce the number of execution, is to use a Multi Trigger: when one of the triggers is validated, the automation is started. I will see at the end of the blog article how we can change automation in this way.

trigger:
  - platform: time_pattern
    minutes: "/5"

Automation is started every 5 minutes

The Conditions

Here we will find a lot of tests to be sure we are closing at the right moment.

condition:
    - condition: time
      alias: "Time 13~20"
      after: "12:30:00"
      before: "18:00:00"
    - condition: or
      conditions:
        - condition: template
          # If automation was never triggered
          value_template: "{{ states.automation.close_cover_based_on_afternoon_temperature.attributes.last_triggered == none }}"
        - condition: template
          # If automation not played in the last 8 hours (means played only the day before)
          value_template: "{{ ( as_timestamp(now()) - as_timestamp(state_attr('automation.close_cover_based_on_afternoon_temperature', 'last_triggered')) |int(0)) > 28800 }}"
    - condition: template
      value_template: "{{ states.sensor.netatmo_maison_willems_indoor_namodule1_temperature.state|float > states.sensor.capteur_mouvement_salon_temperature.state|float + 2 }}"
    - condition: numeric_state
      entity_id: sensor.capteur_mouvement_salon_temperature
      above: 20

Time
The window covers I want to control are south-exposed, for this reason, I'm going to execute the automation only during the afternoon when the sun is completely facing the windows: after: "12:30:00" before: "18:00:00"

Not executed already

- condition: or
      conditions:
        - condition: template
          # If automation was never triggered
          value_template: "{{ states.automation.close_cover_based_on_afternoon_temperature.attributes.last_triggered == none }}"
        - condition: template
          # If automation not played in the last 8 hours (means played only the day before)
          value_template: "{{ ( as_timestamp(now()) - as_timestamp(state_attr('automation.close_cover_based_on_afternoon_temperature', 'last_triggered')) |int(0)) > 28800 }}"

This part of the script, which seems hard to understand I know, is used to check if the automation was already fired (until the execution) or never executed at all (necessary for the first execution or if the last time was long away that historic data are removed).
For this check, we use the last_triggered property on the automation itself, checking if it none or if the last execution was fired more than 8 hours before. Why 8 hours? Never mind, in the end, you just need to put here a value preventing the execution in the same timeframe (12h30 to 18h) and allowing the execution the day after (18h to 12h30). The value 8 is covering both 2 cases: greater than 6:30 hours (18-12h30) and less than 18:30 hours (12h30 - 18h).

Temperature

    - condition: template
      value_template: "{{ states.sensor.netatmo_maison_willems_indoor_namodule1_temperature.state|float > states.sensor.capteur_mouvement_salon_temperature.state|float + 2 }}"
    - condition: numeric_state
      entity_id: sensor.capteur_mouvement_salon_temperature
      above: 20

The 2 other conditions are checking the internal and external temperature.
For the internal, second condition, I'm checking only the temperature sensor in the room where I control the covers and it must be above 20 degrees to trigger the automation.
The other condition is checking the difference between the internal and the external temperature: the external must be at least 2 degrees greater than the internal.
* states.sensor.netatmo_maison_willems_indoor_namodule1_temperature.state|float external module
* states.sensor.capteur_movement_salon_temperature.state|float + 2 internal module + 2 degrees.

The Action

If everything is validated, the covers are closed.

  action:
    - service: cover.set_cover_position
      data:
        entity_id:
          - cover.salon_n1_6
          - cover.salon_n2
          - cover.salon_n3_12
          - cover.salon_n4_14
          - cover.chambre_jardin_3
        position: 40

All the covers I want to control are placed at 40%. Not completely closed, but it is enough to reduce the light entering the room.
I added an additional cover in a separate room without creating another action. It is only to simplify the management as the exposure is the same.

If we put it all together the script is the following:

- id: cover_closes_weather
  alias: "Close cover based on afternoon temperature"
  trigger:
    - platform: time_pattern
      minutes: "/5"
  condition:
    - condition: time
      alias: "Time 13~20"
      after: "12:30:00"
      before: "18:00:00"
    - condition: or
      conditions:
        - condition: template
          # If automation was never triggered
          value_template: "{{ states.automation.close_cover_based_on_afternoon_temperature.attributes.last_triggered == none }}"
        - condition: template
          # If automation not played in the last 8 hours (means played only the day before)
          value_template: "{{ ( as_timestamp(now()) - as_timestamp(state_attr('automation.close_cover_based_on_afternoon_temperature', 'last_triggered')) |int(0)) > 28800 }}"
    - condition: template
      value_template: "{{ states.sensor.netatmo_maison_willems_indoor_namodule1_temperature.state|float > states.sensor.capteur_mouvement_salon_temperature.state|float + 2 }}"
    - condition: numeric_state
      entity_id: sensor.capteur_mouvement_salon_temperature
      above: 20
  action:
    - service: cover.set_cover_position
      data:
        entity_id:
          - cover.salon_n1_6
          - cover.salon_n2
          - cover.salon_n3_12
          - cover.salon_n4_14
          - cover.chambre_jardin_3
        position: 40

I used it for the last 2 years and there is a big difference in the temperature feeling you have when the covers are closed. So it is a big game changer for me.

Different triggers to reduce the number of execution

As I said at the beginning, we can find a different way to manage the trigger, instead of the simple time_pattern. This will contribute to reducing the number of executions: even if the action is not fired, we are entering in the conditions check, using a little bit of your CPU.

If we get back our automation, the real information we need to trigger the automation is the temperature: external is more than 2 degrees greater than internal and internal is above 20 degrees.
An example of what we can change:

automation:
  trigger:
    - platform: template
      value_template: "{{ states.sensor.netatmo_maison_willems_indoor_namodule1_temperature.state|float > states.sensor.capteur_mouvement_salon_temperature.state|float + 2 }}"
      for:
        minutes: 5

In this way, we are triggering based on the external vs internal condition, and we check if the value remains true for at least 5 minutes.
We could add a second trigger about the internal temperature only, but we have to keep in mind that the trigger is evaluated with an or condition: if at least one is true, the action script is executed (but maybe conditions prevent it to be fired).

    - platform: numeric_state
      entity_id: sensor.capteur_mouvement_salon_temperature
      above: 20

It is up to you to define what is the best trigger in your situation, and what you are ready to accept in terms of the number of "false" executions.

Future enhancement

This is the version I used so far but the action was "wrongly" fired sometime. As it is based only on temperature, in the summer all the conditions can be valid even if it is rainy outside. With these weather conditions, the internal temperature is not increasing because the sun is not going through the windows.
At the end of summer, I installed some new external motion sensors I can use to add a new parameter: light intensity.

What I added is a test about the lux parameter, which I'm already using to trigger the external spots.
But this is another story 😎

Do you know the Philips Hue Switch? When you are simply binding it to lights, all the buttons get a specific function over those specific lights: toggle, increase or decrease intensity, and play a scenario. But I never used some of those buttons.

I'm going to describe everything we will see in this blog post using my actual configuration with Zigbee2MQTT. But by changing a little bit the event part, what we will see can be adapted to any ZigBee add-on.

The Direct Binding

The standard way to configure a button/switch is by binding it to a light or a group of lights within the addon.

There is a huge advantage to doing this: the button and the light(s) are hardly connected, which means they can interact directly even without the home assistant or the zigbee2mqtt. In this way, never mind if you are restarting/upgrading/... your home assistant, the lights can be powered on and off using the physical button configured for this.

The side effect is that, at least within the Zigbee2MQTT add-on, you can do only a simple bind: the switch/button will do what is intended to do by default.

Button events

A different way to use buttons or switches is by detecting the generated events and then automating things over them.
But I started saying the side effects of this: events just go to Home Assistant if your ZigBee automation is started and home assistant can execute the automation only if the core is up too. So you can have some buttons going offline during "maintenance operation". It is for me an important point because can be a pain point for your family if you are geeking a lot with your home assistant 😅😱

What events are produced by my switch

Each button/switch produces all the time an event that is sent to Home Assistant. This means you have nothing to do more within your configuration to move from binding to event configuration.
But, what are the events produced by your button? It depends on the button you are using and sometimes even the brand can change the way events are generated.

To discover this event you can start a listener in the developer tools section of the home assistant, and, as I said at the beginning the event depends on your add-on: for Deconz is deconz_event, for ZHA is zha_event, ... And what about ZigBee2MQTT? The difference is that events are sent as messages on the message broker. So, instead of listening to an event, you can listen to a message topic. 😎

I'm doing this directly on the terminal. Do not know if there is a different way for this, but it is not too complex this way.

mosquitto_sub -h 127.0.0.1 -v -t "zigbee2mqtt/switch_entree"

The important part is in the -t parameter (the topic): you have to put the name of your device after the zigbee2mqtt.

WARNING: in the latest version of mosquito it seems you can't log in without strong authentication. You should then add to the previous command the -u and -P parameters to provide the username and password.

Once the script is executed, if an event of the device you want to check comes up, you will see it on the screen.

In the screenshot, you have all the action related to the Philips Hue Switch (the first generation): on_press, up_press, up_press_release, ...
You can then use the desired ones within your automation, and even add other parameters coming in each event to trigger your action differently.

If following these steps is not allowing you to see the events, you can change the topic or listen for all the events coming from ZigBee2MQTT. For this just use the wildcard as the topic name: -t "zigbee2mqtt/#"
In this way, you will see a lot of events if you have a big network!

The Automation

Now we have all the information we need, we can set all up in the automation to control what we want.
I provide here an example:

- alias: Switch Toggle Entree
  id: switch_toggle_entree
  trigger:
    platform: mqtt
    topic: "zigbee2mqtt/switch_entree_02"
  condition:
    condition: template
    value_template: '{{ "on_press" == trigger.payload_json.action }}'
  action:
    entity_id: light.entree
    service: light.toggle

- alias: Switch Toggle Escalier
  id: switch_toggle_escalier
  trigger:
    platform: mqtt
    topic: "zigbee2mqtt/switch_entree_02"
  condition:
    condition: template
    value_template: '{{ "off_press" == trigger.payload_json.action }}'
  action:
    entity_id: light.escalier
    service: light.toggle

The switch's upper button toggles a light, and the "off button" another one. The toggle service is just changing the state based on the actual one: if powered on, the light will be switched off; and the opposite.

But, as we are within automation, there is a world opened for us 😎 We can change the light intensity based on the hour of the day: if it is after midnight but before 7 AM the lith is powered on at 30%, 100% all other hours.

Here is where you have to consider if the side effect can have a huge impact compared to what you gain entering the automation scripts.

What to control depends on the connected devices you have but there are infinite possibilities: start the light randomly, play music if presence is detected somewhere around the home, ... I show here a simple script controlled by automation to start a random light at a random hour.

The script

Add the following script in your scripts configuration file (ie scripts.yaml)

light_duration:
  mode: parallel 
  description: "Turns on a light for a while, and then turns it off"
  fields:
    light:
      description: "A specific light"
      example: "light.bedroom"
    duration:
      description: "How long the light should be on in minutes"
      example: "25"
  sequence:
    - service: homeassistant.turn_on
      data:
        entity_id: "{{ light }}"
    - delay: "{{ duration }}"
    - service: homeassistant.turn_off
      data:
        entity_id: "{{ light }}"

I found it somewhere on the net a while ago, but I don't remember exactly where (so, sorry about the missing reference if you are the original writer of the script 😅).

The script is executing sequentially the turn_on, delay and turn_off, each of these steps is getting a variable: the light (or it can be any device with ON/OFF mode) to control and the global duration.

The parallel at the beginning allows several lights to be started in the same timeframe.

If you use a different mode, a previously started script can be killed and so the lights will never be turned off. I preferred the parallel to have an even more random simulation.

The automation

The automation will then start the script providing the correct parameters.

- id: random_away_lights
  alias: "Random Away Lights"
  mode: parallel 
  trigger:
    - platform: time_pattern
      minutes: "/30"
  condition:
    - condition: state
      entity_id: input_boolean.away
      state: "on"
    - condition: sun
      after: sunset
      after_offset: "-00:30:00"
    - condition: time
      before: "23:59:00"
  action:
    service: script.light_duration
    data:
      light: "{{states.group.simulation_lights.attributes.entity_id | random}}"
      duration: "00:{{ '{:02}'.format(range(5,30) | random | int) }}:00"

The trigger I'm using a simple time_pattern: the automation is started every 30 minutes. I preferred this to a specific time or event because we can be outside the home even after the specific chosen event. To understand this, imagine you decide to start the automation at 20h and then, in the condition you have to add a check "if I'm not at home". If this check is false the automation stop without any execution. But, if you leave the home at 20h05 it will never be triggered again. To fix this you can create a second automation linked to the "going out event" but personally I find it easy to understand with a simple time pattern. There is a code executed every 30 minutes, but in the end, home assistant is mainly doing nothing.

The condition is a group of checks. It is executed only if:

• the away boolean is true. In my case, the boolean is set to true when I set the alarm in "away mode".

• We are after the sunset, or better 30 minutes before the sunset using the offset I put. So I simulate the presence only if it is dark outside

• until a specific hour. The script goes ahead doing stuff until 23h59.

The action is where we are then doing the magic: the previous configuration script is executed with the two variables (light and duration) filled dynamically up.

The light choice is made using
{{states.group.simulation_lights.attributes.entity_id | random}}
I created a group with a list of lights I want to use to simulate the presence. I put only the lights within the rooms visible from the outside.

simulation_lights:
  name: Lights Presence Simulation
  entities:
    - light.salle_manger
    - light.cuisine_table
    - light.bureau_marco
    - light.salon_corner

The random function is used to select randomly 😎 within the provided list. The result is the entity ID to use.

The duration is selected in a similar way with
"00:{{ '{:02}'.format(range(5,30) | random | int) }}:00"
The final result is a string like 00:10:00, so we have the number of minutes the light must be kept on.
To understand the script:

• '{:02}' is giving the number of digits of the final "number". Here we are saying that the format must always be a two digits string. 5 will be 05. If we have a different format the delay procedure in the script will fail with an error.

• range(5,30) says we want any number between 5 and 30 (minutes).

• random nothing to add I think

• int is to convert the result as a number without a decimal.
  If we put it all together the script can be read as the following: select a random number between 5 and 30, converted it into an integer, and then formatted as 2 digit string.

If we get the whole automation at once, every 30 minutes the automation is started and if the conditions are met, a light within the defined group is selected and turned on for a random time between 5 and 30.

You can change any of the parameters I described, to adapt everything to your particular case.

To simplify the management I decided to use events to trigger input_boolean flags, and then use the boolean value to trigger what was needed. In this case, if I want to add events I don't need to change a lot of automation because the boolean value is making an abstraction layer.

Holidays Flag

I'll try to drive you to my solution using an example. What about if you want to adapt your home automation on holiday? Following what I said just before, I added a holidays flag

This flag is then used in automation I want to change when I'm not at home for a "long period". For example the water heater:

It is started during the night but only if the holiday flag is off.

Control the flag

And now, how to know if I'm on holiday or not? A simple way to control it, as it is a flag, is switching it manually. But, in 2022, who is still doing manual things? 😂
In Home Assistant there is a Google Calendar integration that allows you to download all the events from one, or more, calendars in a google account. Each of these events became a home assistant event... and then the rest is everything you already know 😎

When installing the integration you can add it a read or read/write access to the calendars. In some cases, you would like to create new events from home assistant (Did not use it on my side already).

Once connected you can see the list of calendars you are managing in your google account, each of them is giving an entity in home assistant

Oh, what's that homeautomation calendar? 🤩 I created it to separate my personal events, from the ones I would like to use to control the automation. But it is not necessary to do it in this way.

From now on, you can create contition or trigger in automation script based on what happens on the calendar entity.

- alias: Calendar Holidays Event
  id: calendar_holidays_event
  trigger:
    - platform: calendar
      event: start
      entity_id: calendar.homeautomation
    - platform: calendar
      event: end
      entity_id: calendar.homeautomation
  condition:
    - condition: template
      value_template: "{{ 'Holidays' in trigger.calendar_event.summary }}"
  action:
    - if:
        - "{{ trigger.event == 'start' }}"
      then:
        - service: input_boolean.turn_on
          entity_id: input_boolean.vacation
      else:
        - service: input_boolean.turn_off
          entity_id: input_boolean.vacation
  mode: queued

In this example, the automation is triggered by the start and end calendar events, but filtered only for events with a title starting with Holidays.

Create your calendar event, and then let the home automate 😎
Once synchronized with Home Assistant, the calendar.homeautomation entity will give you the information about the first detected event:

message: Holidays
all_day: true
start_time: '2023-02-11 00:00:00'
end_time: '2023-02-18 00:00:00'
location: ''
description: ''
offset_reached: false
friendly_name: Homeautomation

As I have a separate calendar to control the automation, the holidays putting in this one can be different from the real holidays days. In the example with the water heater, I would like to start back all the automation the day before I come back home.