DEV Community: Google Developer Group

AlphaEvolve: Evaluator Harnesses, JAX, and the Boundaries of Autonomous Algorithm Discovery

Cedric Sebastian — Tue, 01 Sep 2026 02:23:36 +0000

AlphaEvolve shows that LLM-guided evolutionary search can produce improved algorithms when candidate quality can be evaluated automatically. Its limits reveal an equally important lesson: an autonomous search system can only optimize for what its evaluator can recognize.

In 2025, Google DeepMind reported that AlphaEvolve found a procedure for multiplying two 4 × 4 complex-valued matrices with 48 scalar multiplications, one fewer than two recursive levels of Strassen’s method. The one-multiplication reduction made the headline. The search loop that found it explains why the result matters beyond matrix multiplication.

Now, we will explore AlphaEvolve to better understand it.

What is AlphaEvolve?

AlphaEvolve is an autonomous evolutionary AI coding agent developed by Google DeepMind that combines language-model proposals with evolutionary search. It uses two of Google’s frontier Gemini models in complementary roles:

Gemini Flash generates high-throughput proposals, expanding the breadth of ideas explored.
Gemini Pro adds greater depth through occasional suggestions from the more capable model.

The paper does not disclose the exact sampling mixture.

AlphaEvolve illustrates how AI has evolved from producing generic, repetitive output to building advanced systems that pair large language models (LLMs) with evolutionary-search harnesses.

The word “autonomous” needs a clear boundary. Humans define the problem, provide the initial program and evaluation code, supply optional context, and mark the code regions that AlphaEvolve may modify. The system then conducts a sustained search within those constraints. This goes well beyond asking a model for a single answer, but it does not make AlphaEvolve an independent scientist who chooses questions or standards of evidence.

AlphaEvolve extends FunSearch, DeepMind’s earlier system for evolving a selected function within a human-written program. AlphaEvolve can modify much larger regions of code, optimize multiple scores simultaneously, and run evaluations for hours in parallel. The expansion is substantial, but the underlying pattern is inherited: language-model variation followed by executable selection.

How does it work?

AlphaEvolve advanced outline. The diagram illustrates how its process works as explained below.

The loop could be demonstrated like this:

User input A user supplies an existing algorithm or program, evaluation code, and optional context about the problem.
Prompt sampler A prompt sampler then selects previous candidates from a program database and gives them to the Gemini models for revision.
Gemini models Create new candidates by proposing code changes, usually returning patches instead of rewriting the whole program.
Evaluator pool Multiple candidates can be evaluated in parallel. Inexpensive checks can filter out invalid or poor candidates before more costly evaluations are run. The evaluation code and the environment in which it runs together form the evaluator harness. This harness determines how each candidate is executed, tested, timed, and scored.
Program database Candidates that receive strong evaluation scores are returned to the database, where they can be chosen again in further generations. The model provides variation by changing the code, while the evaluator provides the selection pressure that determines which changes remain.

AlphaEvolve generates and modifies programs, runs them through an automated evaluator, retains promising candidates, and uses their performance to guide the next generation. This process lets the system evaluate far more candidate programs than we could explore manually on a scale humans can’t examine without sacrificing accuracy, although the reliability of that search still depends on what the evaluator measures.

AlphaEvolve revolutionizes how we work by letting us formulate problems, design evaluators to test them, and constrain the search space. The evolutionary system decides which candidates survive, and human researchers decide whether the resulting score reflects meaningful progress. The evaluator is only one part of the system . In other words, the evaluator matters, but it’s only one part of a much larger human-guided system. AlphaEvolve’s limited ablation studies suggest that its performance depends on several factors, including model capability, evolutionary selection, prompt adaptation, available context, and how much of the code the system is allowed to modify. While the overall loop may appear straightforward, it is supported by several interacting components that surprisingly make the system more complex in practice (Novikov et al., 2025). For the results to be reliable, these mechanisms also need to be paired with a well-designed evaluator.

Results with evidence level distinction

AlphaEvolve’s public record contains three kinds of evidence: artifacts outsiders can verify, production measurements reported by Google, and later work that extends an artifact without reproducing the original search.

Keeping these categories separate prevents a verified mathematical construction from giving proprietary deployment claims more certainty than they warrant.

Demonstrated and checkable. DeepMind released an exact rank-48 decomposition and verification code for multiplying 4 × 4 matrices over complex coefficients. Here, rank counts the bilinear scalar multiplications in the construction. It does not measure wall-clock speed. Additions, memory traffic, numerical stability, coefficient arithmetic, and target hardware can outweigh the benefit of saving one multiplication.

DeepMind initially described the result as the first improvement in 56 years over the complex rank-49 baseline associated with Strassen’s 1969 method. The publication record complicates that priority claim. In 2024, Kaporin reported a numerical complex rank-48 scheme. AlphaEvolve’s contribution is better described as an exact, publicly checkable construction found by the system. Dumas et al. (2025) then transformed that artifact into a 48-multiplication algorithm with rational coefficients. Their work corroborates and extends the construction, but it does not reproduce DeepMind’s search system, which remains closed.

Developer-reported. Google reports that an AlphaEvolve scheduling heuristic, first validated in simulation and then deployed, recovers an average of 0.7% of its worldwide compute resources. The white paper also reports an average 23% speedup across evaluated Pallas matrix-multiplication kernel shapes and about a 1% reduction in Gemini training time. For the kernel study, realistic input shapes were divided between optimization and evaluation sets and measured on TPUs. This provides a useful generalization check, but the workloads, raw timing records, and production environment remain proprietary. These figures are therefore first-party measurements rather than independently audited results.

The same qualification applies to DeepMind’s report that AlphaEvolve matched the best-known construction on roughly 75% of more than 50 mathematical problems and improved on it in roughly 20%. The public report does not fully document the problem-selection protocol or provide a precise denominator. In a May 2026 update, DeepMind reported that AlphaEvolve had become a regular tool for designing next-generation TPUs and had produced a Spanner heuristic that cut write amplification by 20%. These claims came after the 2025 white paper and, like the earlier figures, have not been independently audited.

System Constraints & Bottlenecks

AlphaEvolve’s main boundary is automated evaluability. Tasks that require manual experiments, subjective judgment, or evidence unavailable to the harness do not fit the current loop. Even machine-gradeable tasks can fail in quieter ways. A proxy may reward the wrong behavior, public tests may invite overfitting, omitted edge cases may hide invalid programs, and noisy timing may favor a candidate that will not survive a different device or compiler version. Multi-objective scores add another judgment call because their weights determine what the search may sacrifice.

The concern is empirical, not merely philosophical. In a small 2026 circle-packing preprint (Ishibashi et al., 2026) found generated programs that exploited weaknesses in the evaluator and reported more such hacks from the more capable model they tested. The study examined another harness on one benchmark, so it is evidence of a general failure mode, not an audit of AlphaEvolve’s published results.

A stronger harness would combine exact validity checks where possible with hidden holdouts, adversarial cases, repeated measurements, cross-device tests, versioned environments, independent reimplementation, and human inspection of finalists. These controls raise costs. That cost limits how many candidates can be evaluated and which problems are economically searchable. Model quality, context, representation, compute budget, and editable scope remain bottlenecks even when the evaluator is sound.

Human Adaptation, Decision, and Judgement

Many people are afraid of AI because its capabilities have advanced far faster than expected, but fear will never help us. We should adapt, learn, and use AI as a collaborative brainstorming partner that helps us think better and strengthen our arguments. One-sided perspectives can create new mistakes even as we try to solve existing ones.

AlphaEvolve makes this distinction especially clear. Human judgment enters both before and after the search. Researchers choose the objective, decide what code may change, construct the evaluation environment, and set acceptable constraints and tradeoffs. Once the search is complete, people still have to determine whether the winning program is valid, robust, deployable, and scientifically meaningful, while considering the consequences of putting it into practice. AlphaEvolve itself relies on automated evaluators to score proposed programs, making human choices about objectives and evaluation central to what the system ultimately discovers.

A benchmark score cannot make those decisions. The evidence therefore supports treating AlphaEvolve as a research instrument that operates under human scientific judgment, not as a replacement for it.

Its value lies in expanding the range and persistence of algorithmic search, while responsibility for defining the problem, interpreting the results, and deciding what counts as a meaningful discovery remains with people.

What JAX changes

JAX can reduce the cost of repeated numerical evaluation. It cannot determine whether the evaluator represents the right scientific objective.

That distinction separates AlphaEvolve’s documented JAX use from broader hypotheses about what the pairing might eventually enable.

JAX already appears in the published work. AlphaEvolve used JAX and Optax while evolving tensor-decomposition search code, and it optimized a tiling heuristic for a Pallas kernel used in Gemini training. Pallas is an experimental JAX kernel language that gives programmers fine-grained control over code for GPUs and TPUs, including data movement through fast on-chip memory.

Three JAX transformations are especially relevant:

jax.jit traces and compiles compatible numerical functions for a target device. Repeated calls can reuse the compiled executable when input types and relevant static arguments remain compatible.
jax.vmap maps one function across a batch axis. It can batch evaluations over inputs or parameter settings, but it does not merge structurally different candidate programs into one computation.
jax.grad differentiates scalar-output functions. It could support continuous optimization inside a candidate when the inner objective is differentiable, but it does not differentiate AlphaEvolve's discrete outer search.

During compilation, JAX traces a compatible Python function into an internal representation called a jaxpr, lowers it to StableHLO, and passes the lowered program to XLA to produce an executable for a CPU, GPU, or TPU. A compiler intermediate representation is simply a structured form between source code and machine instructions that allows compilers to analyze and transform it.

This stack makes a broader research program both feasible and practical. AlphaEvolve could propose new kernels, solver components, optimizers, or training-loop components, while JAX could compile and vectorize repeated evaluations for efficient execution on accelerators. For promising candidates, automatic differentiation could help tune internal parameters by supplying gradients to an optimizer, provided the inner objective is differentiable and scalar-valued. This remains a hypothesis about how the search space could be expanded, not a demonstrated path toward general intelligence.

The economics depend on how similar the candidates are. Repeated evaluations of the same jitted candidate can amortize compilation costs, while changes to the code, shapes, dtypes, or static parameters may require new tracing and compilation. Structurally heterogeneous programs may therefore erase the throughput advantage. A credible experiment would also evaluate correctness, speed, memory use, numerical stability, and behavior across unseen data, shapes, devices, and compiler versions.

AlphaEvolve combined with JAX could broaden the practical search space for numerical components when compilation costs can be amortized. That same acceleration makes evaluator quality even more consequential:

A flawed harness can reward the wrong behavior at a greater scale.

This strengthens the case for automated algorithm search, but it is not evidence of autonomous science without human control.

References

AlphaEvolve Team. (2025, May 14). AlphaEvolve: A Gemini-powered coding agent for designing advanced algorithms. Google DeepMind. https://deepmind.google/blog/alphaevolve-a-gemini-powered-coding-agent-for-designing-advanced-algorithms/

AlphaEvolve Team. (2026, May 7). AlphaEvolve: How our Gemini-powered coding agent is scaling impact across fields. Google DeepMind. https://deepmind.google/blog/alphaevolve-impact/

Dumas, J.-G., Pernet, C., & Sedoglavic, A. (2025). A non-commutative algorithm for multiplying 4x4 matrices using 48 non-complex multiplications (arXiv:2506.13242, Version 7) [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2506.13242

Google DeepMind. (2025). Results of AlphaEvolve [Data set and computer software]. GitHub. https://github.com/google-deepmind/alphaevolve_results

Ishibashi, Y., Yano, T., & Oyamada, M. (2026). Effective harness engineering for algorithm discovery with coding agents (arXiv:2605.15221, Version 1) [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2605.15221

JAX Authors. (n.d.-a). Ahead-of-time lowering and compilation. JAX documentation. Retrieved August 29, 2026, from https://docs.jax.dev/en/latest/aot.html

JAX Authors. (n.d.-b). Pallas: Custom kernels in JAX. JAX documentation. Retrieved August 29, 2026, from https://docs.jax.dev/en/latest/401/pallas.html

JAX Authors. (n.d.-c). Transformations: grad and vmap. JAX documentation. Retrieved August 29, 2026, from https://docs.jax.dev/en/latest/101/transformations.html

Kaporin, I. E. (2024). Finding complex-valued solutions of Brent equations using nonlinear least squares. Computational Mathematics and Mathematical Physics, 64(9), 1881–1891. https://doi.org/10.1134/S0965542524701021

Novikov, A., Vũ, N., Eisenberger, M., Dupont, E., Huang, P.-S., Wagner, A. Z., Shirobokov, S., Kozlovskii, B., Ruiz, F. J. R., Mehrabian, A., Kumar, M. P., See, A., Chaudhuri, S., Holland, G., Davies, A., Nowozin, S., Kohli, P., & Balog, M. (2025). AlphaEvolve: A coding agent for scientific and algorithmic discovery [White paper]. arXiv. https://doi.org/10.48550/arXiv.2506.13131

Romera-Paredes, B., Barekatain, M., Novikov, A., Balog, M., Kumar, M. P., Dupont, E., Ruiz, F. J. R., Ellenberg, J. S., Wang, P., Fawzi, O., Kohli, P., & Fawzi, A. (2024). Mathematical discoveries from program search with large language models. Nature, 625(7995), 468–475. https://doi.org/10.1038/s41586-023-06924-6

Google Antigravity Comes to VS Code: Agentic Coding Without Leaving Your Editor

Caleb Duff — Sat, 29 Aug 2026 12:58:53 +0000

If you've tried an "agentic" AI coding tool recently, there's a good chance it asked you to switch editors entirely. Google's own agent-first IDE, Antigravity, launched in November 2025 with exactly that trade-off: full agentic power, but only inside its own dedicated desktop application.

That trade-off just went away. Google has shipped Antigravity extensions for VS Code, Visual Studio, JetBrains, and Zed, bringing the same agent, the same review workflow, and the same account into the editor you've already spent years configuring exactly the way you like it.

This post walks through what the VS Code extension actually is, how it fits into Antigravity's broader architecture, how to install and configure it, and most importantly; how its permission system keeps an agent that can read files, run terminal commands, and drive a real browser from doing anything you haven't explicitly allowed.

By the end of this article, you will be able to:

Explain how the extension relates to the full Antigravity 2.0 desktop app and the agy CLI
Install and authenticate the extension inside VS Code
Work through the agent side panel, implementation plans, and walkthroughs
Configure the permission engine so the agent only does what you approve
Lock down its browser subagent so it never touches your personal Chrome data

New to Antigravity generally? Start with Google's own primer: Antigravity 2.0 Overview

Prerequisites

To follow along hands-on, you'll need:

VS Code version 1.90 or later, on macOS, Linux, or Windows
A Google Account on any Antigravity plan (the free tier is enough), or an enterprise account enabled for Gemini Enterprise
About five minutes for the first-time sign-in and backend install

You can also read this purely as an architecture and workflow walkthrough; every step is explained, not just shown.

1. Where the Extension Fits in Antigravity's Architecture

It helps to know there are actually three doors into the same house:

[ Antigravity 2.0 ] ── the full desktop app, a dedicated fork of VS Code
[ Antigravity CLI (agy) ] ── the same agent, driven from your terminal
[ IDE Extensions ] ── the same agent, embedded in an editor you already run
        │
        ▼
[ Local `agy` backend service ] (installed automatically on first launch)
        │
        ▼
[ Antigravity Agent Runtime ]
   (planning, terminal execution, browser subagent — powered by Gemini)

The extension itself is deliberately thin: a side panel, an inline diff viewer, and a renderer for the agent's plans and artifacts, all sitting on top of your existing VS Code install. On first launch, it silently installs a local agy backend service on your machine, the same engine that powers the standalone desktop app and the CLI. Because of that shared backend, sign-in is unified across every surface: authenticate once, and the same entitlement, permissions, and conversation history follow you whether you open Antigravity from VS Code, JetBrains, or a terminal.

Worth knowing: the full Antigravity 2.0 app is a genuine fork of VS Code, so if you ever outgrow the extension, migrating is mostly a matter of importing your settings. But if your editor setup is already exactly how you want it, the extension gets you the same agent without asking you to leave.

2. Install and Sign In

Getting running takes two short steps.

Step A: Install from the Marketplace

Open the Extensions view (Ctrl+Shift+X on Windows/Linux, Cmd+Shift+X on macOS)
Search for Google Antigravity, published by Google

Click Install

Step B: Sign In and Let Setup Finish

Click the Antigravity icon in the Activity Bar
Sign in with your Google Account
The extension automatically installs the local agy backend service in the background, there's no separate terminal setup to do yourself

Note: you don't need a paid plan to try this. The free tier is enough to install and start using the extension. Enterprise teams instead authenticate against a Gemini Enterprise–enabled account, which ties usage to org-level budgets and IAM policies rather than a personal quota, useful if you want every developer's agent usage centrally governed from day one.

3. Working With the Agent, Not Just Prompting It

Once you're signed in, a panel on the right side of the editor becomes your main workspace. From there you can spin up new conversations, attach images, switch agent modes, and pick between models; all without a context switch away from your code. As a task runs, a toolbar above the input tracks open file changes, running terminal processes, and any artifacts the agent has produced, so you always know what it's currently touching.

Implementation Plans: Review Before Anything Changes

For any non-trivial request, the agent doesn't jump straight to editing files. The standard workflow will be to first produce an implementation plan, which is basically an artifact describing exactly what it intends to change and why and, unless your review policy is set to always proceed, it pauses for your sign-off (permission) before touching a single line.

The useful part isn't just the pause; it's that you can comment directly on the plan itself. Want a smaller scope, a different library, or to correct a misunderstanding before any code gets written? Leave the comment, and either hit Proceed to continue as-is or submit your feedback for the agent to revise the plan against. Think of it as reviewing a pull request description before the pull request exists.

Walkthroughs and Browser Testing: Built for Web Developers Specifically

After a task finishes, the agent can generate a walkthrough, which is basically an artifact summarizing what actually changed and why useful when you're reviewing work after the fact rather than watching it happen live.

More interesting for web development specifically: Antigravity can open, read, and actuate a real local Chrome browser through a dedicated browser subagent. Practically, that means after building a feature, the agent can launch your dev server, click through the UI it just built, capture screenshots, and save the interaction as a video artifact, all before you ever tab over to localhost yourself to check its work.

4. Configure What the Agent Is Allowed to Do

This is the section that matters most if you plan to use this on real projects, not just toy demos/projects.

Every sensitive action the agent takes, like reading a file, running a command, hitting a URL, calling an MCP tool is represented as a permission resource in the form action(target). Each one is evaluated against three lists:

Deny — blocked immediately, no exceptions
Ask — the agent pauses and requests your explicit approval
Allow — runs automatically, no prompt

Strict precedence always runs Deny > Ask > Allow. If a command matches both an Allow rule and a Deny rule, the Deny rule wins. That single fact makes it easy to build a safety net: broadly allow the things you trust, then explicitly deny the handful of commands you never want run automatically, regardless of any other rule.

Step-by-Step Decision Hierarchy

   Incoming Tool Action: action(target)
                    │
                    ▼
        ┌───────────────────────┐
        │  1. Check DENY List   │ ──(Matches?)──► ❌ Blocked Immediately
        └───────────┬───────────┘
                    │ No
                    ▼
        ┌───────────────────────┐
        │   2. Check ASK List   │ ──(Matches?)──► ❓ Pause & Prompt User
        └───────────┬───────────┘
                    │ No
                    ▼
        ┌───────────────────────┐
        │  3. Check ALLOW List  │ ──(Matches?)──► ✅ Run Automatically
        └───────────┬───────────┘
                    │ No
                    ▼
        ┌───────────────────────┐
        │  4. Default Fallback  │ ──────────────► ❓ Prompt User
        └───────────────────────┘

A reasonable starting configuration looks something like this:

# ==========================================
# 1. DENY (Highest Precedence - Always Blocked)
# ==========================================
command(rm -rf .*)
command(git push --force.*)
write_file(\.env.*)

# ==========================================
# 2. ASK (Pause & Prompt for Approval)
# ==========================================
command(git push.*)
command(npm publish)
execute_url(*)

# ==========================================
# 3. ALLOW (Runs Automatically)
# ==========================================
command(git status)
command(git log.*)
command(npm run (test|lint|build).*)
read_file(src/.*)
read_url(developer\.mozilla\.org)

By default, reading and writing files inside your active project workspace is auto-allowed, while everything else; like arbitrary shell commands, MCP tools, and any interactive browser action falls back to Ask unless you configure otherwise. That default is deliberately conservative, it lets the agent move quickly on the code it's supposed to touch, while still checking in before it runs a command or browses a URL you haven't vetted.

5. Lock Down the Browser Subagent

Because the agent can drive an actual browser, it gets its own layer of isolation on top of the general permission engine:

A separate Chrome profile. The browser subagent runs inside a completely isolated profile, not the Chrome window you're logged into. It never sees your saved passwords, cookies, or open tabs.
An allowlist and denylist for URLs, giving you a second, independent layer of control over exactly which domains the browser subagent is permitted to load or interact with, beyond the general read_url / execute_url permission rules.
A full off-switch. If you'd rather the agent never touch a browser at all, the Browser Tools setting disables the capability entirely.
Terminal sandboxing (currently in preview on macOS/Linux, Windows coming soon). When enabled, your permission grants double as the sandbox's actual filesystem and network allowlists, so even an approved command executes inside an isolated container rather than directly against your machine.

PS:
At first, when I started prompting, the agent wasn't able to provide an implementation plan due to a Pre-Tool Hook Issue detected.

And so, instead of creating or modifying my files, it simply printed out the codes with an instruction to copy & paste the codes into my files as shown below:

I used the method One (1) to apply a quick fix to the Pre-Tool Execution Hook Issue and voila! (Issue Resolved).

Where to Go Next

Try the smallest possible version: install the extension, ask it to fix one small bug or add one small feature, and actually read the implementation plan before clicking Proceed. Watch the toolbar as it works to see which files, commands, and artifacts it touches along the way.

Are you planning to move to the full Antigravity 2.0 desktop app, or sticking with your current editor and just adding the extension? I'd love to hear how the plan-and-review workflow compares to inline-suggestion tools like Copilot in the comments.

Why AI Websites All Look the Same and How to Build Something Different

Mfonobong Umondia — Sat, 29 Aug 2026 01:38:54 +0000

If you've built a website with AI recently, there is a good chance it looks familiar. Maybe you have seen the same oversized hero headline, the same purple-to-blue gradient, the same rounded cards, the same floating dashboard mockup, and the same neatly arranged feature sections somewhere else. You may have even generated versions of the exact same website idea with different AI website builders and noticed that the results are surprisingly similar.

So, why do AI websites look the same?

The answer has less to do with AI being incapable of creativity and more to do with the patterns these tools have learned, the components they rely on, the defaults they are designed around, and the way we prompt them.

Since we all started building with AI, almost every website seems to be following a familiar formula, and I am sure that by simply reading this article, one or two websites have already come to your mind.

You will often see a huge centered headline sitting in the middle of the screen, or to the left side of the screen with a short paragraph underneath it and a call to action button. There is probably going to be a purple-to-blue gradient glowing softly behind everything. Then come three or four rounded cards explaining the product, a row of customer logos, more whitespace, a testimonial sitting inside a soft-shadowed box, and one more call-to-action before the footer.

Somewhere along the way as you scroll, you start wondering whether you've seen this exact website before. Honestly, you probably have, because the strange part is that these websites usually look pretty good. They are responsive, the spacing feels intentional, the typography is clean, the animations are smooth, and every button actually works. The problem is that they do not feel particularly memorable. They could belong to almost any company building almost any product, and that is exactly where the problem begins.

This is one of the strangest side effects of AI-assisted development becoming mainstream. Tools such as Lovable, v0, Bolt, Base44, Google AI Studio, Replit, and Claude can take a plain-language description and turn it into a working interface in minutes. But somewhere between typing your "build me a portfolio website" prompt and watching the interface come to life, a huge number of us end up with something that looks suspiciously like everyone else's website.

So why does this keep happening, and more importantly, how do you actually get AI to build something that feels like it belongs to you and nobody else?

That is what this article is about.

What Do AI-Generated Websites Usually Look Like?

If you spend enough time scrolling through AI-generated interfaces, you will start noticing similarities everywhere. There is not one single official AI website design style, but there is a recognizable visual pattern that keeps appearing across different AI website builders and coding tools.

You will recognize most of these patterns on sight: large bold hero headlines, centered layouts, left aligned layouts, generous whitespace, rounded cards, soft drop shadows, subtle borders, gradient backgrounds in shades of purple, or blue, glassmorphism panels, floating dashboard mockups, friendly sans-serif typography, a strip of "trusted by" logos, three-column feature sections, testimonials tucked into cards, pricing tables, animated backgrounds, and dark mode toggles etc.

None of these choices are inherently bad. In fact, most of them are genuinely good design decisions that make sense for a huge number of products. Rounded cards can make an interface feel approachable, whitespace can improve readability, blue can communicate trust, and a clear hero section can help visitors understand a product quickly.

The real problem appears when everyone reaches for the same good choices at the same time, because that is when those choices stop feeling distinctive and start feeling like a generic wallpaper.

A website can be technically excellent and still be visually forgettable. It can have good accessibility, responsive layouts, clean code, thoughtful interactions, and strong performance while still looking almost identical to hundreds of other AI-generated websites.

That distinction matters because the goal of good design is not simply to make something look good. The goal is to communicate something specific to a specific audience in a way that feels appropriate to the product and memorable enough to leave an impression.

Why Do AI Websites Look the Same?

Large language models are prediction systems at their core, which means they do not approach a blank page in exactly the same way a human designer would. When you ask an AI system to build something, it draws from patterns it has encountered across enormous amounts of existing material.

If thousands of examples of modern Agency websites contain a centered hero, a bold headline, rounded cards, a blue or purple accent, a three-column feature grid, customer logos, and testimonials, those patterns become highly probable responses when someone asks an AI to create a modern Agency website.

In other words, when you say, "Build a modern portfolio website for a Community Manager," you are effectively asking the model to produce something that resembles what people generally consider a modern community manager portfolio to look like.

AI happens to be extremely good at that particular task, which is exactly why the first output can feel polished and forgettable at the same time.

It usually lands somewhere within the familiar patterns it has learned, and those familiar patterns are rarely where the most distinctive design decisions live.

There is also a second, much more human layer to this problem.

Most of us prompt AI with almost identical language without realizing it. We type things like "build a clean, modern, professional website," "create a sleek and beautiful landing page," or "make it minimal, premium and visually impressive."

These phrases sound like creative direction to a human, but to a model they are extremely broad categories rather than specific instructions. They tell the AI what general group you want to belong to, but they do not tell it what makes your product different from everyone else in that group.

It is similar to walking into a restaurant - say Pasta De Café for instance and telling the chef to give you something delicious. The chef technically has enormous freedom, but because you have not given them any meaningful constraints, they will probably make something that appeals to majority of the customers that order from the café.

If instead you tell the chef you want spicy Asun pasta with an extra portion of Asun, paired with a cold-pressed ginger and pineapple drink, the request suddenly becomes much more specific.

The same principle applies to AI website design.

The more generic your creative direction is, the more likely the model is to rely on familiar patterns. The more specific your direction becomes, the more opportunity you give the model to create something that feels intentional.

There is also a technical reason AI-generated websites often look similar.

A significant number of code-first AI website builders generate interfaces using the same popular open-source technologies and component systems. Tailwind CSS and shadcn/ui are particularly influential in modern React-based interfaces, and when different products are being generated from similar building blocks, their buttons, cards, inputs, modals, spacing, borders, and other interface elements can begin to resemble one another.

The component library itself is not necessarily the problem. Reusable components are one of the reasons developers can build products quickly and consistently.

The problem begins when the defaults start determining the composition instead of simply helping express the product.

Why AI Website Builders Keep Producing Similar Designs

AI website builders have developed into several different categories, and understanding those categories helps explain why the same visual patterns can appear across tools that otherwise work very differently.

Design-first tools such as Framer AI and Webflow AI are focused heavily on visual composition and allow users to generate or refine websites inside visual editors. They are particularly useful for marketing websites, portfolios, landing pages, and other experiences where visual presentation is a major priority.

All-in-one AI website builders such as Bolt, 10Web, and Squarespace AI place more emphasis on speed and convenience. You can describe your business, choose a general direction, and receive a website that may already contain the structure, copy, imagery, branding, and other elements you need to get started.

Code-first tools such as Lovable, v0, Claude, Google AI Studio, and Replit Agent operate closer to the development side of the spectrum. They can generate actual application code and, depending on the tool and project, connect interfaces to databases, authentication systems, APIs, and other functionality.

These tools are solving different problems, yet their outputs can still converge visually.

That tells us something important.

The sameness is not simply a problem with one particular AI website builder. It is a broader design-system problem created by a combination of shared training patterns, popular frameworks, component libraries, design trends, user prompts, and the natural tendency of AI systems to choose familiar solutions when they are given insufficient direction.

Other People Have Noticed This Too

The idea that AI-generated websites are becoming visually similar is not just something you notice after spending too much time looking at landing pages.

Other designers and developers have started documenting the same phenomenon.

Joshua Snoddy's article on why AI-generated websites look the same examines the recurring use of purple gradients, glass cards, centered hero sections, Inter typography, and shadcn/ui components across tools such as Lovable, v0, and Bolt. His analysis points toward the same underlying issue: AI tools tend to reach for safe and familiar design patterns because those patterns are heavily represented in the material from which models learn. Joshua Snoddy's analysis

InterfaceKit makes a similar argument, explaining how AI-generated websites can become interchangeable when a prompt does not contain enough product-specific creative direction. The tool fills the gaps with familiar patterns, resulting in an interface that works but does not necessarily communicate a distinctive visual identity. InterfaceKit's analysis

Sailop has also compared several AI website builders using the same short brief and documented similarities between the generated results, including centered heroes, three-column feature grids, Lucide icons, blue-to-purple gradients, and similar typography. Sailop's AI website builder comparison

These examples are useful because they show that the phenomenon is not limited to one tool.

Different AI builders can arrive at remarkably similar visual conclusions when they receive similarly vague instructions.

And to be clear, this is not happening because someone at an AI company decided that every website should be purple. The real explanation is much more interesting.

Common AI Website Design Patterns

Once you start noticing these patterns, it becomes difficult to stop seeing them.

One of the most common patterns is the use of a single accent color against a white or near-white background. In technology products, that accent often lands somewhere around blue, indigo, violet, or purple because these colors are already deeply associated with modern software and digital products.

Typography follows a similar pattern.

AI-generated interfaces frequently reach for fonts such as Inter, Poppins, Manrope, and other clean sans-serif typefaces because they are highly legible, widely available, and already common across modern digital products.

Then, we also have rounded corners, buttons, cards, inputs, modals, containers, and sometimes entire sections can end up sharing the same generous border radius. This creates visual consistency, but when every component has the same treatment, the interface can begin to feel mechanically assembled.

Feature sections often always look like bento grids or collections of cards because they provide an easy way to organize information into responsive blocks without requiring a more unusual compositional decision.

Depth is commonly created with soft shadows, subtle borders, gradients, and glassmorphism rather than texture, strong outlines, unusual layering, or more expressive visual systems.

The page structure itself also tends to follow a familiar sequence: Hero → social proof → features → testimonials → pricing → FAQ → final call-to-action.

There is nothing inherently wrong with this structure. In fact, it works because it follows a familiar marketing logic that helps visitors understand a product, build trust, address their questions, and eventually make a decision.

The problem begins when every product uses the same structure alongside the same visual language, typography, imagery, and component styles. At that point, the experience becomes predictable. The website is easy to understand, easy to generate, easy to implement, and often easy to optimize for conversions. The only problem is that it is not always memorable.

What AI-Generated Websites Actually Look Like in Practice

Imagine a founder typing this into any AI website builder of their choice:

Build a landing page for my AI productivity app. Make it modern, clean, and professional.

Within a short amount of time, they may have a well-designed website that looks like a thousand other websites. The result can look genuinely polished, with thoughtful spacing, clean typography, smooth interactions, and a logical page structure. It can also look remarkably similar to the last five AI productivity websites you saw.

Now imagine a restaurant owner using an AI website builder. They type “restaurant,” select a general style, and receive a website with food photography, a hero banner, a menu section, testimonials, an about section, opening hours, and a contact area.

Again, it works, and it can look good. The problem is that it may have been generated from the same template logic, design patterns, and assumptions that have already been used to create thousands of other restaurant websites. The website does its job, but there may be very little about it that makes the restaurant itself feel distinctive.

Now consider a designer working at an agency.

They use an AI website builder to generate a first draft for a client, but instead of accepting the first result, they replace the stock photography with the client's actual photography, change the typography, adjust the spacing, introduce the brand's actual color system, restructure several sections, and redesign the feature area around the client's content.

The final website can look nothing like the AI's initial output, not because the tool suddenly became more creative, but because the human continued the design process and gave it better direction.

Finally, imagine a developer asking Google AI Studio to create a pricing table. The first version produces a familiar collection of pricing cards. Instead of accepting it, the developer asks for an editorial-style comparison table with rows instead of cards, a strong visual treatment for the recommended plan, specific brand colors, custom typography, and a completely different visual hierarchy.

The second version can look dramatically different from the first, even though the same tool is being used. The difference is the direction.

This is the pattern worth remembering: the tools that produce generic websites and the tools that produce distinctive websites can very often be the exact same tools. What changes is the amount of specific, constrained, referenced direction a human provides before accepting the result.

AI Website Prompts That Can Break the Pattern (Try This Yourself)

The fastest way to understand this is to run the same brief through an AI website builder twice, first with a generic prompt and then with a deliberate one.

The Prompt That Produces the Generic Look

Try this:

Build a modern landing page for a personal finance app aimed at young professionals. Use a clean, premium aesthetic with a hero section, features, testimonials, and pricing.

This is an extremely common style of prompt, and it leaves almost every important visual decision open.

The AI has to decide what “modern” means, what “premium” means, which colors to use, which typography to choose, how to structure the page, what type of imagery belongs in the hero, how the feature section should work, and even what visual personality the brand should have.

When you provide no strong opinion, the model has to supply one. And it will usually draw from the patterns it has seen most often.

I tested this exact prompt across three AI website builders and looked specifically at the hero sections.

AI-generated finance landing page created with Lovable using the same generic prompt

AI-generated finance landing page created with Google AI Studio using the same generic prompt

AI-generated finance landing page created with v0 using the same generic prompt

Look closely at the three results.

The exact implementation is different, but the visual language is surprisingly familiar. You can see similar approaches to hierarchy, spacing, composition, and the general idea of what a modern financial product landing page should look like.

You may also notice something else that happens surprisingly often with AI-generated websites: the tools invent random company names, testimonials, statistics, product claims, and other content because the prompt did not provide real information.

This is another reason why generic AI-generated websites can feel artificial. The design is generic, and the content is generic too.

Now Rewrite the Same Brief With Real Direction

Instead of simply asking for a "modern" finance website, try giving the AI a visual and communication problem to solve:

Create a fintech landing page for first-time investors aged 22 to 30 who feel intimidated by traditional financial products. The visual language should feel like a modern financial magazine rather than a banking website. Use strong editorial typography, real-world financial illustrations, and clear data storytelling. Avoid corporate blue, generic stock photography, and dashboard-heavy layouts. Make the financial information feel approachable instead of intimidating.

The difference is significant because now the model has an audience, an emotional problem to address, a visual reference, a communication goal, specific things to avoid, and a clear aesthetic direction. Instead of simply decorating a generic SaaS page, the model now has a much more specific problem to solve.

A Second Experiment: The Mfon Plant Care App

If you want to test this yourself, use one consistent product idea across several AI website builders rather than changing the product for every experiment.

For this example, imagine a fictional houseplant care app called Mfon.

Start with this control prompt:

Build a landing page for Mfon, a mobile app that helps people take care of their houseplants. Make it modern, clean, and professional, with a hero section, features, testimonials, and a pricing section.

Then compare that result with several highly specific directions.

Editorial Direction

Design a landing page for Mfon, a houseplant care app. Use an early-2000s print magazine editorial layout rather than a typical SaaS page. Use an asymmetrical grid, an oversized serif headline, generous negative space, and a muted sage-and-cream palette using only #F4F1EA and #3C4A3B. Do not use gradients, drop shadows, or rounded corners. Let the feature section read like a magazine spread with pull quotes rather than a bento grid, and let the testimonial read like a quoted editorial excerpt rather than a carousel with headshots.

Brutalist Direction

Design a landing page for Mfon, a houseplant care app. Use a brutalist web design direction that feels raw, high-contrast, and intentionally unpolished. Use a pure black background, a single acid-green accent at #B4FF39, and one heavy monospace font throughout. Use thick borders instead of shadows, avoid gradients and soft corners entirely, and replace stock photography with bold typographic statements and simple line-art plant illustrations. The layout should feel intentionally rigid and grid-locked, closer to a zine than a polished startup website.

Retro Botanical Direction

Design a landing page for Mfon, a houseplant care app. Use a visual direction inspired by 1970s botanical prints and retro travel posters. Use terracotta, mustard yellow, and forest green, pairing a slightly quirky display font for headlines with a plain serif for body copy. Use an illustrated hero image instead of photography and make the imagery feel like a vintage botanical poster. Let the feature section feel like a vintage seed-packet catalog instead of a modern card grid, and avoid anything that looks like a typical technology startup, including gradients, glassmorphism, and generic SaaS icons.

Notice what is happening here.

The product has not changed, and the functionality has not changed either. The target audience has not necessarily changed. What changed is the creative direction, and that is why your prompt matters so much.

If you run the generic prompt across three or four different AI website builders, you can compare how much their outputs converge when they are given the same vague instructions. Then, run the more specific creative direction through those same tools and compare the results.

You can also take the original generic output and ask the tool to redesign it using one of the new visual directions.

That transformation can be even more interesting than generating a completely new website because it demonstrates something important: the AI was capable of moving away from its defaults once someone gave it a reason to.

The One Rule That Changes Everything: Say What You Don't Want

Here is a rule worth keeping close whenever you are prompting an AI website builder: do not only describe what you want; describe what you do not want as well.

Most prompts are purely additive. We tell the AI to add a hero, add a feature section, add testimonials, make the website beautiful, make it modern, make it responsive, and make it professional.

But distinctive design often requires subtraction rather than addition.

Compare a generic prompt such as:

Create a modern landing page for an AI productivity tool.

with a more deliberate version:

Create a landing page for an AI productivity tool, but do not use purple-to-blue gradients, glassmorphism, floating dashboard screenshots, three-column feature cards, generic stock photography, rounded cards in every section, or vague SaaS copy such as "supercharge your productivity." Use editorial typography, an asymmetric layout, warm neutral colors, real product screenshots, and specific copy that speaks directly to independent creators.

The second prompt gives the AI boundaries.

Those boundaries are useful because they force the model to solve the design problem instead of falling back on its most familiar patterns.

This is one of the biggest misconceptions about prompting AI for creative work. People sometimes assume that giving an AI more constraints will make the result less creative. In many cases, the opposite is true.

When everything is possible, the model can easily return to the safest and most familiar option. When certain options are explicitly removed, it has to explore what else could work.

Use System Instructions as Your Design Guardrails

This is also where system instructions become useful.

Most people focus on the prompt they are typing in the moment and forget that they can establish a set of rules that the AI should follow throughout an entire project.

If you are building a website across multiple pages and iterations, system instructions can act as your design guardrails. They can establish the visual rules that should remain consistent throughout the project rather than forcing you to repeat the same instructions every time you ask the AI to build something new.

You can define your approved fonts, exact color palette, spacing system, border radius, image style, typography hierarchy, accessibility requirements, animation preferences, and, perhaps most importantly, what the AI should avoid.

For example, you could establish a rule like this:

For this entire project, do not use gradients, glassmorphism, excessive rounded cards, purple or blue accents, generic SaaS layouts, or stock photography. Use the provided brand colors, editorial typography, asymmetric layouts, and sharp edges throughout. Do not introduce new fonts or colors unless explicitly requested.

This becomes particularly useful as the project gets larger.

You might spend an hour moving a website away from the generic SaaS aesthetic, only to ask the AI to add a new pricing section and suddenly receive the same three-column rounded pricing cards you were trying to escape.

The problem is not necessarily that the model ignored you. The problem may simply be that you never established the instruction as a persistent design rule.

System instructions are not a replacement for detailed prompts, but they can provide a consistent foundation for the individual prompts you use throughout the build.

How to Make an AI-Generated Website Look Unique

The single biggest shift you can make is trading vague adjectives for real references.

Telling an AI to make something feel premium gives it very little to work with. Telling it to make something feel like a contemporary luxury editorial magazine rather than a typical SaaS dashboard gives it a much more specific concept to interpret.

You can even combine unrelated visual worlds intentionally.

You could ask for a project management app inspired by a Japanese stationery brand, a developer portfolio with the visual language of a music festival, or a fintech landing page inspired by an independent fashion magazine.

These combinations create tension between familiar categories, and that tension can lead to more distinctive design decisions.

It also helps enormously to give the model hard constraints instead of leaving everything open-ended. Specify your exact hex codes, approved fonts, preferred corner style, whether you want illustrations or photography, whether the layout should be symmetrical or asymmetric, whether you want dense information or generous whitespace, the visual references you like, and the visual patterns you absolutely do not want.

An open-ended prompt quietly gives the AI permission to fall back on its defaults.

A tightly scoped prompt forces it to solve the problem within your visual world rather than relying on the familiar patterns it has learned from the internet.

Give AI Your Real Content

Real content matters far more than most people expect.

If you ask an AI website builder to create three testimonials, it will probably produce generic testimonials about how a product changed someone's life, improved their workflow, or helped them become more productive.

The layout will then be designed around placeholder content that may bear very little resemblance to what your actual customers will say.

A headline with six words behaves differently from a headline with eighteen words. A testimonial with thirty words shapes a section differently from one with one hundred words. A product with three features requires a different information hierarchy from one with twelve.

When you provide your actual copy, screenshots, product details, customer stories, statistics, pricing, and brand assets, the AI has much more real material to work with when building the interface.

Instead of designing a beautiful shell around imaginary content, it can design around the actual communication problem your website needs to solve.

Tell the AI Who the Website Is For

Your audience should also be part of your design prompt because there is no such thing as a website designed for everyone.

A page built for developers can lean into technical terminology, dense information, code snippets, documentation-style layouts, and monospace accents.

A website built for a luxury consumer audience may need stronger imagery, more restraint, more whitespace, and significantly less dashboard-heavy UI.

A website built for young creators can afford to be more expressive, playful, colorful, and visually loud.

Naming the audience explicitly gives the AI a much clearer target because you are no longer asking it to create a modern website.

You are asking it to create a particular experience for a particular group of people. That is a much more useful design problem.

Stop Designing the Entire Website With One Giant Prompt

It is tempting to tell an AI website builder everything at once.

You give it the product description, the navigation, the hero, the features, the testimonials, pricing, the FAQ, the footer, the animations, the responsiveness, and your entire visual direction in one massive prompt and then wait for the finished website.

Sometimes this works, but I can tell you for free that it is not always the best way to get a distinctive result.

Breaking the work into smaller pieces gives you significantly more control.

You can start with the hero, evaluate it, refine it, and then move on to the navigation.

You can build the feature section separately and deliberately choose whether it should use cards, editorial layouts, illustrations, tables, timelines, or another structure.

You can design the pricing section independently rather than allowing the AI to automatically repeat the same card pattern used everywhere else.

This also makes it much easier to diagnose what is not working.

If five sections in a row all use the same rounded card structure, you can explicitly tell the AI that the problem is repetition and ask it to introduce visual variation.

That is much more useful than simply saying, “Make it better,” because “Make it better” tells the AI almost nothing.

Using a follow up prompt like “Five consecutive sections currently use identical rounded cards. Redesign the fourth section as an editorial two-column layout with a large product image and supporting text” gives the model a specific problem to solve.

The difference is that you are no longer asking the AI for a vague improvement. You are identifying what is not working, explaining why it is not working, and giving it a clear direction for what to change. That kind of feedback makes the design process far more intentional.

Do Not Forget the Fundamentals

There is an important distinction between originality and unnecessary complexity.

A website does not become good simply because it looks unusual. Contrast still matters, readable typography, keyboard navigation, clear focus states, responsive behavior, loading performance, and even accessibility still matters.

If you are asking an AI website builder to create something visually experimental, you should still tell it to maintain good accessibility, usability, and performance practices.

The goal is not to make your website as unusual as possible. The goal is to make it distinctive without making it difficult to use. Good design knows when to follow familiar conventions and when to break them.

You can also ask it to keep the implementation lightweight by avoiding unnecessary animation, oversized assets, excessive dependencies, and visual effects that do not add meaningful value.

A website that looks incredibly distinctive but takes ten seconds to load is not necessarily a successful website.

The goal is not to escape every established design principle, but to stop using established patterns without thinking.

Changed Your Mind Halfway Through? Here's How to Pivot

One of the most useful things to understand about AI-assisted development is that you do not have to start over just because the first visual direction is not working.

You can redirect the aesthetic partway through the project as long as you are clear about what should remain and what should change.

The cleanest way to do this is to separate content and functionality from visual style.

Your copy, feature list, product information, database, authentication, and core functionality may be worth keeping.

Your typography, colors, spacing, shadows, border radius, imagery, and overall visual direction may be what you actually want to replace.

A prompt like this can help:

Keep the existing content, structure, and functionality exactly as they are, but redesign the entire visual direction. Move away from the current SaaS aesthetic and toward an editorial magazine-style layout. Use an asymmetric grid, a bold serif headline font, a warm neutral palette, and sharper visual hierarchy instead of the current blue-and-white design. Do not modify the existing functionality or content.

Naming the old direction and the new direction gives the model a clear before-and-after reference.

If you only want to change the mood without redesigning everything, be specific about the scope:

Keep the layout and structure exactly as they are, but change the color palette, typography, imagery, and shadow style so the website feels warmer and more handmade rather than corporate.

This type of request is much more predictable than simply asking the AI to make the website feel different.

You can also create a fork of your design if the tool or workflow allows it.

Instead of overwriting your existing version, duplicate it and experiment with a completely different visual direction. This gives you two versions to compare rather than forcing yourself to commit to a change before you know whether it works.

And if you are struggling to decide what the new direction should actually be, ask the AI to act as an art director rather than an implementer.

Give it your existing content and ask it to propose three completely different visual directions for the same product, explaining the typography, color palette, layout system, imagery, component style, and emotional positioning of each direction.

That approach mirrors how a real design process often works. You explore possibilities before deciding which direction deserves to become the final design.

Your First AI-Generated Website Was Never Supposed to Be the Final One

Your first AI-generated website was never meant to be the finished website.

It is closer to a first draft that answers a much simpler question than the one that actually matters.

The first version tells you whether the thing can be built.

The next several versions help you determine whether it actually feels like you.

That shift in mindset changes how you use AI website builders completely.

Instead of generating once and shipping, the better process looks more like generating, inspecting, questioning, directing, regenerating, comparing, and refining until the website starts to communicate something specific.

The first output is useful because it gives you something to react to. It does not have to be good enough to publish.

In fact, sometimes the most useful thing the first version can do is show you exactly what you do not want.

Before You Call Your AI-Generated Website Done, Ask Yourself This

Before accepting an AI-generated design as final, run through a simple mental checklist.

Would the website still feel like your brand if the logo disappeared?
Could your competitor replace your logo with theirs and still have a website that looks completely natural?
Does every section use the same card pattern?
Was the color palette chosen deliberately, or did the design slowly drift toward the familiar blue-to-purple range?
Are the typography choices connected to your brand, audience, or product?
Does the copy sound like something your company would actually say, or does it sound like AI wrote it?
Are the images real, relevant, and specific to your product, or are they generic visual decoration?
Does the website communicate something about your personality, positioning, or audience that another company could not easily copy?

And perhaps the most important question is this:

*If you saw ten websites like this in a row tomorrow, would you remember this one?
*

If the honest answer is no, there is probably still more direction worth giving.

Frequently Asked Questions About AI-Generated Websites

Why do AI websites look the same?

AI websites often look the same because AI website builders rely on familiar design patterns, popular component libraries, common frameworks, existing web design conventions, and similar user prompts. When an AI receives a vague request such as "create a modern professional website," it tends to select design patterns that are widely used and statistically familiar rather than inventing an entirely new visual language.

Why do AI-generated websites use purple and blue so often?

Purple and blue are already common colors in technology, SaaS, and AI branding because they are associated with concepts such as trust, innovation, intelligence, and modern technology. AI website builders have also learned from large amounts of existing digital design where these colors are heavily represented, making them common choices when the user does not provide a specific brand palette.

How can I make my AI-generated website unique?

You can make an AI-generated website more unique by giving the AI specific visual references, brand colors, typography, layout constraints, real content, audience information, and a clear list of patterns to avoid. Instead of asking for a "modern" or "premium" website, explain the visual world you want the website to belong to and explicitly tell the AI what should not appear.

Can AI create original website designs?

Yes, AI can create highly distinctive website designs when it receives specific creative direction, strong references, meaningful constraints, and enough context about the product and audience. The first generated version may rely heavily on familiar patterns, but iterative prompting and human art direction can move the design significantly away from those defaults.

Which AI website builders can create websites from prompts?

Several AI-powered website and development tools can generate websites or web applications from natural-language instructions, including Lovable, v0, Bolt, Replit, Google AI Studio, Framer AI, and other AI website builders. Their capabilities and outputs vary depending on the tool, model, prompt, available components, and the amount of human direction provided.

Are AI-generated websites bad design?

Not necessarily. An AI-generated website can have excellent typography, spacing, responsiveness, accessibility, performance, and usability while still feeling generic. The problem is not that the design was created with AI; the problem is that the final design may rely too heavily on familiar defaults without enough human art direction.

So Here's My Actual Point

AI is not incapable of originality. It is simply very good at giving us what we repeatedly ask for.

When thousands of people tell AI to build something modern, clean, premium, minimal, professional, and beautiful without explaining what any of those words mean for their particular product, it makes sense that the results begin to converge.

When the same people use the same AI website builders, the same component libraries, the same frameworks, the same fonts, the same gradients, the same layouts, and the same prompts, that convergence becomes even more obvious.

The solution is not to stop using AI, it is to stop treating the first generated version as the finished design.

The websites that do not look AI-made were often still built with AI. Someone simply refused to stop at the first draft and kept giving direction until the website stopped looking like everyone else's and started looking like theirs.

Your call to action today is to go back to the last AI-generated website you built and ask yourself one question:

What about this makes it unmistakably mine?

If the answer is nothing, do not throw the entire website away.

Go back into your AI website builder and start directing it differently. Tell it what to remove. Give it references. Give it real content. Give it your colors, your personality, your audience, your weird ideas, and your non-negotiables. Ask it to break the patterns it keeps reaching for, and do not be afraid to reject a perfectly functional design simply because it feels too familiar.

Because AI can build the website, but you still have to give it a point of view.

Do not just use AI to make something that works.

Use it to make something people remember.

Need a Website That Actually Feels Like Yours?

This is also how I approach the websites and web applications I build for clients. I do not believe in simply handing an AI a generic prompt, accepting the first generated interface, and calling the job done. AI can make the development process significantly faster, but speed should not come at the expense of strategy, usability, or visual identity.

If you are building a website or web application and want something that is functional, intentional, and actually feels like your brand rather than another AI-generated template, I would love to chat.

You can reach me at umondiamfonobong@gmail.com and tell me a little about what you are building, what you need, and where you are currently stuck. So even if you are starting from scratch or already have an AI-generated website that needs a serious design intervention, let's talk.

Managed Inference on Google Cloud: Pairing the Gemini Enterprise Agent Platform with Cloud Run

Caleb Duff — Wed, 12 Aug 2026 15:45:27 +0000

If you have ever wanted to ship an AI-powered application without managing GPUs, model servers, or scaling infrastructure yourself, this guide is for you.

Managed inference simply means letting a cloud provider run the AI model for you: you send a request, the platform handles the compute, and you get a response back. On Google Cloud, the cleanest way to do this today is to pair the Gemini Enterprise Agent Platform (formerly Vertex AI) with Google Cloud Run, dividing responsibilities between the two services. The Agent Platform serves as the orchestration and intelligence engine, while Cloud Run hosts your custom application logic, front-end UIs, or Model Context Protocol (MCP) servers.

By the end of this article, you will be able to:

Explain the hybrid architecture and why each layer exists
Define an AI agent in code using the Agent Development Kit (ADK)
Deploy your app layer to Cloud Run with a single command
Choose between online and batch inference for your workload
Secure and monitor the whole setup in production

New to the underlying concept? Start with Google Cloud's primer: What is AI inference?

Prerequisites

To follow along hands-on, you will need:

A Google Cloud project with billing enabled
The gcloud CLI installed and authenticated
Python 3.10+ and the ADK installed (pip install google-adk)

You can also read this purely as an architecture walkthrough; every step is explained, not just shown.

1. The Architectural Blueprint

This pattern splits your system into independent, auto-scaling tiers:

[ Client / Web UI ] ──> [ Cloud Run Service ] (App Logic / Tool Front End)
                                │
                                ▼
        [ Gemini Enterprise Agent Platform — Agent Runtime ]
            (Orchestration, Intent Analysis, Memory)
                                │
                                ▼
              [ Managed Inference / Model Garden ]
                 (Gemini 3.x Pro / Flash models)

Why split it this way? Each tier scales independently and fails independently. Your web front end can handle a traffic spike without touching the model layer, and you can swap models without redeploying your application code. It also creates a clean security boundary, clients only ever talk to Cloud Run, never directly to the model.

Here is what each layer actually does:

Cloud Run runs your specialized business logic, secures client-facing endpoints with Identity-Aware Proxy (IAP), and hosts external tools, MCP servers, and APIs. Think of it as everything you build.
The Agent Platform (Agent Runtime) manages active agent state, long-term memory, and the model's reasoning steps in a centralized, fully managed runtime. Think of it as everything Google runs for you.

2. Build Your Agent Code with the ADK

Use the open-source Agent Development Kit (ADK) to define your agent's behavior in code and bind it to a model. The key idea to understand: tools are plain Python functions. The ADK reads each function's docstring to decide when and how to call it; so a clear docstring is not documentation nicety, it is part of your agent's logic.

# agent.py
from google.adk.agents import Agent

def call_internal_business_system(query: str) -> str:
    """Invokes secure business workflows deployed on Cloud Run."""
    # Logic to securely call your Cloud Run service URL
    return "Data retrieved from secure internal backend."

# Define an agent that targets a current Gemini model
root_agent = Agent(
    name="enterprise_inference_agent",
    model="gemini-3.5-flash",  # Or another current model from Model Garden
    instruction="You are a data processing assistant using managed inference.",
    tools=[call_internal_business_system],
)

Breaking down the four fields:

name — an identifier for your agent, used in logs and traces.
model — which Gemini model handles the reasoning. Flash models are faster and cheaper; Pro models handle more complex reasoning.
instruction — the agent's system prompt, shaping its behavior on every request.
tools — the Python functions the model is allowed to call. When a user request matches a tool's docstring, the model invokes it.

Note: Gemini 1.0 and 1.5 models (including gemini-1.5-pro) have been retired and now return errors. Always target a currently supported model, such as gemini-3.5-flash, gemini-3.6-flash, or a Gemini 3.x Pro release from Model Garden.

3. Containerize and Deploy the App Layer to Cloud Run

When deploying your orchestration backend or front-end dashboard, the tooling can package and push the container for you. Two small steps get you there.

Step A: Configure Service Account Permissions

In Google Cloud, services do not trust each other by default, your Cloud Run instance needs explicit permission to invoke Agent Platform endpoints. This command grants its service account that permission:

gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
    --member="serviceAccount:YOUR_RUN_SA@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/aiplatform.user"

In plain terms: "let this Cloud Run service call the AI platform." This is the step people most often forget; if your deployed service returns permission errors, come back here first.

Step B: Build and Deploy

The ADK ships with a one-command deployment path. Under the hood, it does three things: builds your container image, pushes it to Artifact Registry, and creates (or updates) the Cloud Run service.

# Deploys your custom agent or tool layer directly to Cloud Run
adk deploy cloud_run \
    --project="YOUR_PROJECT_ID" \
    --region="us-central1" \
    --service_name="agent-inference-backend" \
    path/to/your/agent

Alternatively, the Agents CLI (agents-cli) can scaffold the deployment configuration for a Cloud Run target. For example, agents-cli scaffold enhance --deployment-target cloud_run and works from inside your preferred AI coding tool. Either route wires up your environment variables, including model targets and the public service URL.

4. Online and Batch Inference Routines

Once the plumbing is in place, there are two primary ways to trigger managed inference. Choosing correctly comes down to one question: does a human need the answer right now?

Online inference (low-latency UI): Make synchronous API calls from your Cloud Run front end directly to the deployed agent endpoint for real-time chat, tool calls, or step-by-step reasoning. Example: a customer support chatbot where every second of latency matters.
Batch inference (high-volume data): For large data processing jobs, submit an asynchronous batch prediction job through the Agent Platform SDK. The platform provisions dedicated compute, runs the inference tasks, writes results and logs to Cloud Storage, and tears down the compute automatically when the job completes. Example: classifying 100,000 support tickets overnight; nobody is waiting on a single response, so throughput and cost matter more than latency.

Batch jobs are typically much cheaper per request, so a good rule of thumb is the "Now vs Later" latency and volume test: if you need a prediction in under 2 seconds(quickly) to serve a live user, use online inference; if you have a large volume of data that can wait minutes or hours, use batch inference.

5. Secure and Monitor the Architecture

A demo can skip this section. Production cannot.

Secure the ingress: Wrap your Cloud Run endpoints in Identity-Aware Proxy (IAP) to protect human-in-the-loop dashboards, IAP checks the user's Google identity before traffic ever reaches your code. For agent-to-tool traffic, Agent Gateway can give each agent a unique identity with end-to-end mTLS (mutual TLS, where both sides verify each other) when calling MCP servers on Cloud Run.
Centralize trace logging: Enable the platform's built-in OpenTelemetry tracing (Cloud Trace is on by default for CLI-based deployments). You can visually inspect directed acyclic graphs (DAGs) of execution, a step-by-step map of every reasoning step, model call, and tool invocation — to see exactly how your Gemini models and Cloud Run tools collaborated on an inference task. When an agent gives a strange answer, this trace is how you find out why.

Key Takeaways

Split the responsibilities: Cloud Run for your code, the Agent Platform for orchestration and models. Each tier scales and fails independently.
Tools are just functions: the ADK turns well-documented Python functions into capabilities your agent can call.
Permissions before deployment: grant roles/aiplatform.user to your Cloud Run service account, or nothing else will work.
Match inference mode to workload: online for interactive experiences, batch for high-volume processing.
Secure and trace from day one: IAP at the edge, mTLS between services, OpenTelemetry for visibility.

Where to Go Next

Try the smallest possible version: define a one-tool agent with the ADK, run adk deploy cloud_run, and send it a request. Once that works, everything else in this article is an incremental addition.

Have you tried pairing the Agent Platform with Cloud Run, or are you still on a self-managed inference setup? I would love to hear what your architecture looks like in the comments.

Angular WebMCP — Your App is Now an AI Tool 🔥🚀

Giorgio Galassi — Sat, 08 Aug 2026 10:09:17 +0000

There's a pattern in Angular releases that I've come to appreciate: every major version picks one bet that's slightly ahead of its time. Signals were that bet in v16. Zoneless was that bet in v21. In v22, that bet is WebMCP, and it's a fundamentally different kind of feature — not a framework improvement, but an architectural shift in what an Angular app is.

Let me explain what I mean.

🧭 The Idea: Outside → In

Every Angular feature so far has been about what happens inside the app — how components detect changes, how services are injected, how forms manage state. WebMCP is different: it's about exposing your app's capabilities to the outside, specifically to AI agents running in the browser.

The mental model is simple. Today, an AI assistant browsing your app sees a DOM — pixels and HTML. It can read text and click buttons, but it has no understanding of what your app can do. WebMCP changes that. You declare a set of tools backed by your real Angular services, your real signals, your real DI graph, and any WebMCP-capable agent can discover and call them directly through a typed, described interface you control.

This is different from Agent Skills, which is your app calling out to AI. Two separate features, two directions: WebMCP is agents driving your app; Agent Skills is your app calling AI. Today we're only talking about WebMCP.

🔧 Browser Support

WebMCP is built on the W3C ModelContext API, a draft browser standard. Your tools register on navigator.modelContext and any agent that speaks this protocol can query that object and call them.

As of June 2026, Edge 147 ships it natively, Chrome 149 has an open Origin Trial, Firefox is committed for Q3 2026, and Safari for Q4. Mass adoption is realistically mid-2027, and Angular ships this as experimental — that flag is honest, but the integration is already surprisingly clean.

⚠️ Experimental: provideExperimentalWebMcpTools() is available in Angular 22 but carries no stability guarantees yet. The W3C spec is still evolving; expect API changes before general availability.

🛠️ Building Your First WebMCP Tool

Let's build something concrete. A dashboard shows a list of expenses and we want an AI assistant to ask "what expenses are currently visible?" and get real, live data back — not a DOM scrape or a static API response, but the actual signal state the component is rendering from.

Step 1: The service

// expense.service.ts
import { Service, signal } from '@angular/core';

export interface Expense {
  id: string;
  description: string;
  amount: number;
  currency: string;
  category: ExpenseCategory;
}

export const ExpenseCategory = {
  Accommodation: 'accommodation',
  Transport: 'transport',
  Meals: 'meals',
} as const;

export type ExpenseCategory = typeof ExpenseCategory[keyof typeof ExpenseCategory];

export const CATEGORY_VALUES = Object.values(ExpenseCategory).join(', ');

@Service()
export class ExpenseService {
  private expenses = signal<Expense[]>([
    { id: '1', description: 'Hotel',  amount: 250, currency: 'USD', category: ExpenseCategory.Accommodation },
    { id: '2', description: 'Taxi',   amount: 35,  currency: 'USD', category: ExpenseCategory.Transport },
    { id: '3', description: 'Dinner', amount: 80,  currency: 'USD', category: ExpenseCategory.Meals },
  ]);

  getVisible(): Expense[] {
    return this.expenses();
  }
}

@Service() is Angular 22's new shorthand for @Injectable({ providedIn: 'root' }) — if you want the full picture on that, I covered it in Angular 22 — @Service and injectAsync: Dependency Injection Finally Grows Up. Notice that CATEGORY_VALUES lives right here next to the ExpenseCategory object — we'll use it to keep the tool description in sync automatically.

Step 2: Declaring the tool

Parameters are described using JSON Schema syntax — the same format Angular uses internally and the same format the agent receives.

// expense-mcp.tool.ts
import { declareExperimentalWebMcpTool, inject } from '@angular/core';
import { ExpenseService, ExpenseCategory, CATEGORY_VALUES } from './expense.service';

export const expenseListTool = declareExperimentalWebMcpTool({
  name: 'getVisibleExpenses',
  description: 'Returns the list of expenses currently visible in the dashboard.',
  inputSchema: {
    type: 'object',
    properties: {
      category: {
        type: 'string',
        description: `Filter by expense category. Allowed values: ${CATEGORY_VALUES}.`,
      },
    },
    additionalProperties: false,
  },
  execute: ({ category }: { category?: ExpenseCategory }) => {
    const svc = inject(ExpenseService);
    const all = svc.getVisible();
    const filtered = category ? all.filter(e => e.category === category) : all;
    return { content: [{ type: 'text', text: JSON.stringify(filtered) }] };
  }
});

Four things to notice here.

The return value follows the MCP tool result format. { content: [{ type: 'text', text: '...' }] } is the wire format the agent expects, defined by the Model Context Protocol spec. You don't return a plain object or array directly — you serialise your data into that text field with JSON.stringify, and the agent parses it on its end. This is not Angular-specific; it's the protocol contract every MCP tool must honour.

name and description are instructions to the LLM, not documentation for humans. The agent reads them at runtime to decide whether and how to call the tool, so write them like an OpenAPI spec for an AI: precise, specific, unambiguous.

execute runs inside Angular's injection context, which means inject() works normally and your tool has full access to your DI graph.

CATEGORY_VALUES is derived from the object, not hardcoded. Add a value to ExpenseCategory and the agent description updates automatically, with no second place to maintain.

Step 3: Registering in the app

// app.config.ts
import { provideExperimentalWebMcpTools } from '@angular/core';
import { expenseListTool } from './expense-mcp.tool';

export const appConfig = {
  providers: [
    provideExperimentalWebMcpTools([expenseListTool]),
    // ... rest of your providers
  ]
};

One line in your app config and you're done. From here, any WebMCP-capable agent visiting your app will find getVisibleExpenses in document.modelContext.tools and can call it against the live session.

🔍 What the Agent Actually Sees

When a WebMCP-capable agent inspects the page, this is what it finds on document.modelContext:

{
  "tools": [
    {
      "name": "getVisibleExpenses",
      "description": "Returns the list of expenses currently visible in the dashboard.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "category": {
            "type": "string",
            "description": "Filter by expense category. Allowed values: accommodation, transport, meals."
          }
        },
        "additionalProperties": false
      }
    }
  ]
}

The user says "show me only transport expenses." The agent reads the schema, resolves category: "transport", calls the tool. Angular runs the handler against the live signal state. The agent gets back exactly the filtered rows the dashboard is currently showing — no DOM scraping, no brittle selectors, no static mock data.

⚛️ Signal Forms as Agent Tools

If your app is form-heavy, Angular 22 also ships provideExperimentalWebMcpForms(), which automatically surfaces all your Signal Forms as agent-callable tools without you having to declare each one manually.

// app.config.ts
import { provideExperimentalWebMcpForms } from '@angular/forms/signals';

export const appConfig = {
  providers: [
    provideExperimentalWebMcpForms(),
  ]
};

⚠️ Experimental: provideExperimentalWebMcpForms() is double-experimental — both WebMCP itself and the forms integration are in preview. Treat it as a proof of concept for now.

Each Signal Form becomes a tool the agent can fill and submit. For internal tooling or admin dashboards this is already genuinely useful, and it shows where the Angular team is heading: if Signal Forms are the way to model user intent, they should also be the way to model agent intent.

💡 Beyond the Happy Path

The docs highlight forms as the easy entry point, but the more interesting territory is everything else — read queries, write actions, navigation triggers.

Let's be honest: a read + write pair is where agents become genuinely powerful. Expose getExpenseReports() alongside flagExpense(id, reason) and an agent can query, reason over the data, and act in a single turn. Add permission-awareness by injecting your AuthService inside the execute handler and the agent automatically gets a properly scoped view, seeing only what the current user is authorised to see. You could also expose derived data tools like getSummaryByCategory() — pre-computed aggregates cost fewer tokens and produce faster responses than handing the agent a raw list to process itself.

The general principle worth internalising: anywhere you'd write a hardcoded string describing your domain model, ask whether you can derive it from TypeScript instead. Your types are the single source of truth and the agent's schema should follow from them, not diverge from them.

🔒 One Thing Worth Getting Right Early: Trust

Because execute handlers run inside Angular's injection context with full access to your DI graph, a WebMCP tool is as powerful as the service method it wraps — which means a write tool is a real mutation, not a preview. Before shipping any tool that modifies state, there are three things worth understanding.

Prompt injection in your descriptions. The description and parameter description fields are read by the LLM as trusted context. A malicious site can embed instructions in its own tool descriptions that manipulate the agent's behaviour on other sites — and if your own tool returns user-generated content, that content is another vector. The W3C security considerations doc calls this out explicitly under "Metadata / Description Attacks" and "Output Injection Attacks": never echo unsanitised user content directly from an execute handler.

Angular does not validate inputs for you. The agent is supposed to match the inputSchema you define, but Angular makes no guarantee it does — the execute callback receives whatever the agent sends. The Angular docs are explicit on this: "Consider explicitly validating arguments to the execute function before using them." Treat every input as untrusted, the same way you would a form submission or a query parameter.

The session is the attack surface. The W3C spec's threat model notes that agents inherit the user's authentication context — session cookies, logged-in state, everything. The real risk isn't an anonymous external caller; same-origin constraints handle that. The risk is a legitimate, trusted agent that has been manipulated through prompt injection and then calls your write tools with the user's full permissions. Design accordingly: scope write tools tightly, and never expose an action you wouldn't want triggered automatically on behalf of a logged-in user.

⚠️ The Honest Caveat

The W3C spec is still early and has been changing frequently. Mid-2027 is the realistic mass-adoption target, when both browser default support and enough publisher adoption exist to make it meaningful at scale. For now it's great for internal tools and early experimentation, but it's not ready to ship to anonymous production users.

That said, the direction is set. Your app has always had one interface — the DOM, for humans. WebMCP adds a second one, for agents. How you design that second surface is a new skill worth starting to develop now, before the spec lands and everyone is catching up at once.

If you found this helpful, follow me here and on LinkedIn for more deep dives into Angular, signals, AI, and modern frontend development.

See you in the next one! 🤙🏻
— G.

Zero to Multi-Region: High Availability Serverless with Cloud Run and Cross-Region Failover & Failback

Caleb Duff — Fri, 24 Jul 2026 00:52:30 +0000

Google just made multi-region Cloud Run significantly easier. Here is the full picture; what changed, what it means in practice, and how to build it right.

Most teams discover they need multi-region architecture the hard way and sadly, during an outage. Whether you're running a global e-commerce platform, a real-time gaming API, or a financial services application, users expect your service to be available whenever they need it. There is a conversation that happens in almost every engineering team at some point. It usually starts with a post-mortem. A regional Google Cloud outage or a Cloud Run service that hit a cold start spike, or a single-region deployment that could not handle the latency demands of users spread across Lagos, Nairobi, and London simultaneously, caused enough pain that someone finally asked: why are we only deployed in one region?

The answer is usually one of three things: it felt complex, it felt expensive, or no one had prioritised it yet.

In July 2026, Google moved Cloud Run Service Health to General Availability and the timing was hard to miss. Six days earlier, a power cut at Google's Netherlands data centre had knocked three services offline. The GA release brings automatic cross-region failover to Cloud Run with what Google describes as a two-step setup: add a readiness probe, set minimum instances to at least 1. The load balancer does the rest.

This article covers the full architecture, what Service Health is, how readiness probes underpin it, how to set up the Global Load Balancer correctly, and how to test that failover actually works. It also covers the production details.

What changed: Service Health and readiness probes

Before Service Health, multi-region Cloud Run required you to implement a /health endpoint in your application and configure a separate HTTPS health check at the load balancer level. This worked, but it had a significant gap. The load balancer's health check only knew whether the Cloud Run service endpoint was responding, not whether the individual container instances behind it were actually ready to serve traffic.

Service Health introduces two new capabilities that close this gap:

Readiness probes operate at the container instance level. Cloud Run periodically sends an HTTP request to a path you specify on each running container instance. If the probe fails, Cloud Run stops routing requests to that instance until the probe succeeds again. Critically, a failing readiness probe does not kill the instance (that is what a liveness probe does), it simply marks the instance as not ready for traffic.

Service Health aggregates the readiness state of all container instances in a region into a single regional health signal. This aggregated health status is exposed through the Serverless NEGs (Network Endpoint Groups) for that region. When the Global Load Balancer reads the NEG's health status and sees a region is unhealthy, because enough instances are failing their readiness probes; it automatically reroutes traffic to a healthy region. When the failing region recovers, traffic is gradually restored without any operator action.

The result: failover and failback capabilities are now fully automated, triggered by real instance-level health rather than a synthetic endpoint check.

Container instance (readiness probe fails)
        │
        ▼
Cloud Run aggregates probe results across all instances in the region to determine the overall health status of each regional service
        │
        ▼
Service Health: region marked UNHEALTHY
        │
        ▼
Serverless NEG reports unhealthy status to Global Load Balancer
        │
        ▼
Load Balancer stops routing to this region → shifts traffic to healthy region
        │
        ▼
Region recovers → Load Balancer gradually restores traffic

This is available in all Cloud Run regions at no extra charge beyond the CPU and memory consumed while readiness probes run.

Architecture overview

                    ┌──────────────────────────────────┐
                    │   Global Anycast IP (single IP)  │
                    │   + SSL Certificate (managed)    │
                    └───────────────┬──────────────────┘
                                    │
                    ┌───────────────▼──────────────────┐
                    │  Global External HTTP(S) LB      │
                    │  (URL map + forwarding rules)    │
                    └──────┬──────────────────┬────────┘
                           │                  │
        ┌──────────────────▼──┐         ┌─────▼──────────────────┐
        │  Serverless NEG     │         │  Serverless NEG        │
        │  africa-south1      │         │  us-central1           │
        │  (Service Health    │         │  (Service Health       │
        │   status: healthy)  │         │   status: healthy)     │
        └──────────┬──────────┘         └───────────┬────────────┘
                   │                                │
   ┌───────────────▼───────────┐     ┌──────────────▼──────────────┐
   │  Cloud Run Service        │     │  Cloud Run Service          │
   │  africa-south1            │     │  us-central1                │
   │  Readiness probe: /health │     │  Readiness probe: /health   │
   │  min-instances: 1+        │     │  min-instances: 1+          │
   │  (auto-scales 0–N)        │     │  (auto-scales 0–N)          │
   └───────────────────────────┘     └─────────────────────────────┘

Prerequisites and setup

export PROJECT_ID="your-project-id"
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID \
  --format="value(projectNumber)")
export SERVICE="my-api"
export REGION_A="africa-south1"
export REGION_B="us-central1"
export DOMAIN="api.yourdomain.com"
export IMAGE="gcr.io/${PROJECT_ID}/${SERVICE}:latest"

gcloud config set project $PROJECT_ID

# Enable required APIs
gcloud services enable \
  run.googleapis.com \
  compute.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  networkservices.googleapis.com

# Grant Cloud Build service account the Cloud Run builder role
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${PROJECT_NUMBER}-   compute@developer.gserviceaccount.com" \
  --role="roles/run.builder"

Step 1: Implement the readiness probe endpoint

The first step and the most important one for Service Health to work, is adding a readiness probe endpoint to your application. Unlike the previous/alternative approach where the /health endpoint was for the load balancer's benefit, this endpoint is called directly by Cloud Run on each container instance to determine per-instance readiness.

Two rules from the official docs that matter here:

Use an HTTP/1 endpoint (the Cloud Run default, not HTTP/2)
The endpoint path must match the path in your probe configuration exactly

// Node.js / Express
// Lightweight — no DB calls, no downstream dependencies
// This runs frequently on every instance
app.get('/health', (req, res) => {
  res.status(200).json({
    status: 'healthy',
    region: process.env.REGION,
    timestamp: new Date().toISOString()
  });
});

// If you want the probe to reflect actual readiness
// (e.g. connection pool initialised), you can check internal state:
let isReady = false;
app.get('/health', (req, res) => {
  if (!isReady) {
    return res.status(503).json({ status: 'not_ready' });
  }
  res.status(200).json({ status: 'healthy', region: process.env.REGION });
});

// Set isReady = true after your startup tasks complete
pool.connect().then(() => { isReady = true; });

# Python / FastAPI
import os
from datetime import datetime
from fastapi import FastAPI, Response

app = FastAPI()
is_ready = False

@app.get("/health")
async def readiness_probe(response: Response):
    if not is_ready:
        response.status_code = 503
        return {"status": "not_ready"}
    return {
        "status": "healthy",
        "region": os.environ.get("REGION"),
        "timestamp": datetime.utcnow().isoformat()
    }

@app.on_event("startup")
async def startup_event():
    global is_ready
    # Initialise connections, warm caches, etc.
    await init_database_pool()
    is_ready = True

The is_ready pattern is the key upgrade over a basic /health endpoint. The readiness probe on each instance will return 503 until your startup tasks complete, preventing the load balancer from routing traffic to an instance that is running but not yet ready.

Step 2: Deploy to multiple regions with readiness probes

The gcloud run deploy supports deploying to multiple regions in a single command, and the --readiness-probe flag attaches the probe configuration at deploy time. Failovers require at least two (2) services from different regions.

# Deploy to both regions simultaneously with readiness probe
gcloud run deploy $SERVICE \
  --image=$IMAGE \
  --regions=$REGION_A,$REGION_B \
  --min=1 \
  --max-instances=100 \
  --concurrency=80 \
  --cpu=1 \
  --memory=512Mi \
  --timeout=30s \
  --readiness-probe="httpGet.path=/health" \
  --set-env-vars="ENV=production" \
  --allow-unauthenticated

The --readiness-probe="httpGet.path=/health" flag is the new way to configure probes at deploy time. You can also configure additional probe parameters:

# Full readiness probe configuration
gcloud run deploy $SERVICE \
  --image=$IMAGE \
  --regions=$REGION_A,$REGION_B \
  --min=2 \
  --readiness-probe="httpGet.path=/health,periodSeconds=10,failureThreshold=3,successThreshold=1,timeoutSeconds=5"

Or via YAML service definition (the Terraform-friendly approach):

# service.yaml
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: my-api
spec:
  template:
    metadata:
      annotations:
        autoscaling.knative.dev/minScale: "1"
        autoscaling.knative.dev/maxScale: "100"
    spec:
      containers:
      - image: gcr.io/PROJECT_ID/my-api:latest
        resources:
          limits:
            cpu: "1"
            memory: 512Mi
        env:
        - name: ENV
          value: production
        readinessProbe:
          httpGet:
            path: /health
          periodSeconds: 10
          failureThreshold: 3
          successThreshold: 1
          timeoutSeconds: 5
        livenessProbe:
          httpGet:
            path: /health
          periodSeconds: 30
          failureThreshold: 3

The difference between readiness and liveness probes

Both probe types are supported on Cloud Run. Understanding the distinction is critical:

Readiness probe failure: Cloud Run stops routing requests to that instance. The instance continues running. Once the probe succeeds again, routing resumes. Service Health aggregates these to determine regional health.

Liveness probe failure: Cloud Run restarts the container instance. Use liveness probes for detecting deadlocks or unrecoverable stuck states.

For Service Health's automatic failover, readiness probes are what matter. Liveness probes are a complement, they handle instance-level recovery, while readiness probes handle traffic routing decisions.

Step 3: Set up the global external Application Load Balancer

With the new Service Health model, the load balancer configuration is simpler than before, you no longer need to configure a separate HTTPS health check at the load balancer level. Service Health exposes regional health through the Serverless NEG itself.

Create the backend service

# Single backend service, both regions are added as NEG backends
gcloud compute backend-services create $SERVICE-bs \
  --load-balancing-scheme=EXTERNAL_MANAGED \
  --global

Note: unlike the earlier approach with separate backend services per region, Service Health works with a single backend service that has multiple regional NEG backends. The load balancer reads health from each NEG and routes accordingly.

Reserve a global static IP (Set up a global static external IP address to reach your load balancer:)

gcloud compute addresses create $SERVICE-ip \
  --network-tier=PREMIUM \
  --ip-version=IPV4 \
  --global

export GLOBAL_IP=$(gcloud compute addresses describe $SERVICE-ip \
  --global --format="get(address)")

echo "Global IP: ${GLOBAL_IP}"
# → Update your DNS A record to this IP before proceeding

Create URL map, proxy, and forwarding rules

# Create a URL map to route incoming requests to the backend service:
gcloud compute url-maps create $SERVICE-lb \
  --default-service=$SERVICE-bs

# For HTTPS (recommended for production):
# Create Google-managed SSL certificate
gcloud compute ssl-certificates create $SERVICE-ssl \
  --domains=$DOMAIN \
  --global

# Create the target HTTPS proxy to route requests to your URL map:
gcloud compute target-https-proxies create $SERVICE-https-proxy \
  --url-map=$SERVICE-lb \
  --ssl-certificates=$SERVICE-ssl

# Create the HTTPS forwarding rule  to route incoming requests to the proxy:
gcloud compute forwarding-rules create $SERVICE-https-fr \
  --load-balancing-scheme=EXTERNAL_MANAGED \
  --network-tier=PREMIUM \
  --address=$SERVICE-ip \
  --target-https-proxy=$SERVICE-https-proxy \
  --global \
  --ports=443

# HTTP forwarding rule (redirect to HTTPS)
gcloud compute target-http-proxies create $SERVICE-http-proxy \
  --url-map=$SERVICE-lb

gcloud compute forwarding-rules create $SERVICE-http-fr \
  --load-balancing-scheme=EXTERNAL_MANAGED \
  --network-tier=PREMIUM \
  --address=$SERVICE-ip \
  --target-http-proxy=$SERVICE-http-proxy \
  --global \
  --ports=80

Step 4: Create Serverless NEGs and attach them

# Serverless NEG for africa-south1
gcloud compute network-endpoint-groups create $SERVICE-neg-$REGION_A \
  --region=$REGION_A \
  --network-endpoint-type=serverless \
  --cloud-run-service=$SERVICE

# Serverless NEG for us-central1
gcloud compute network-endpoint-groups create $SERVICE-neg-$REGION_B \
  --region=$REGION_B \
  --network-endpoint-type=serverless \
  --cloud-run-service=$SERVICE

# Add both NEGs to the single backend service
gcloud compute backend-services add-backend $SERVICE-bs \
  --global \
  --network-endpoint-group=$SERVICE-neg-$REGION_A \
  --network-endpoint-group-region=$REGION_A

gcloud compute backend-services add-backend $SERVICE-bs \
  --global \
  --network-endpoint-group=$SERVICE-neg-$REGION_B \
  --network-endpoint-group-region=$REGION_B

At this point, Service Health is active. Cloud Run is running readiness probes on every instance in both regions, aggregating the results into a regional health signal, and the load balancer reads that signal via the Serverless NEGs.

Step 5: Monitor Service Health with Cloud Monitoring

Service Health exposes two metrics through Cloud Monitoring that you should track from day one:

run.googleapis.com/container/instance_count_with_readiness, the number of instances passing their readiness probe per region. Watch this metric to see the health state of your instance pool in each region in real time.

run.googleapis.com/service_health_count, the regional Cloud Run service health as reported to the load balancer. Possible values: HEALTHY, UNHEALTHY, UNKNOWN. The load balancer uses this to make failover decisions. UNKNOWN is reported until the service has enough data from probes to determine health, typically within the first few minutes of deployment.

# View current service health status via gcloud
gcloud run services describe $SERVICE \
  --region=$REGION_A \
  --format="value(status.conditions)"

# Or check via the Console:
# Cloud Run → your service → Metrics tab → "Instance count with readiness"

Set up an alerting policy that fires when service_health_count for any region transitions to UNHEALTHY:

# alert-policy.yaml
displayName: "Cloud Run region unhealthy — failover active"
conditions:
- displayName: "Service health UNHEALTHY"
  conditionThreshold:
    filter: |
      resource.type="cloud_run_revision"
      metric.type="run.googleapis.com/service_health_count"
      metric.labels.health_status="UNHEALTHY"
    comparison: COMPARISON_GT
    thresholdValue: 0
    duration: 60s
    aggregations:
    - alignmentPeriod: 60s
      perSeriesAligner: ALIGN_MAX
notificationChannels:
- projects/${PROJECT_ID}/notificationChannels/YOUR_CHANNEL_ID
documentation:
  content: |
    A Cloud Run region has become unhealthy and traffic is being
    rerouted to the remaining healthy region(s). Investigate the
    failing region's logs and instance readiness metrics immediately.

Step 6: Testing failover

Testing is not optional, it is the only way to know your failover actually works before your users discover it during a real incident.

Method 1: Use the sample application's toggle (for the official sample)

The Google Cloud sample application (golang-samples/run/service-health) includes a built-in toggle button in its UI that marks a region as unhealthy. For production applications, use Method 2.

Method 2: Force readiness probe failure via environment variable

# Redeploy africa-south1 with a flag that makes /health return 503
gcloud run deploy $SERVICE \
  --image=$IMAGE \
  --region=$REGION_A \
  --set-env-vars="FORCE_UNHEALTHY=true,ENV=production"

In your application, check this variable:

app.get('/health', (req, res) => {
  if (process.env.FORCE_UNHEALTHY === 'true') {
    return res.status(503).json({ status: 'forced_unhealthy' });
  }
  res.status(200).json({ status: 'healthy', region: process.env.REGION });
});

Observe the failover sequence

# Get load balancer IP
export LBIP=$(gcloud compute addresses describe $SERVICE-ip \
  --global --format='value(address)')

# Continuous requests — watch region shift in responses
while true; do
  RESPONSE=$(curl -s https://${DOMAIN}/health)
  echo "$(date '+%H:%M:%S') — $RESPONSE"
  sleep 2
done

You should observe:

Requests showing "region": "africa-south1" — normal operation
A mix of responses as the probe failure propagates across instances
All requests showing "region": "us-central1" — failover complete
The service_health_count metric for africa-south1 showing UNHEALTHY

Restore the region:

gcloud run deploy $SERVICE \
  --image=$IMAGE \
  --region=$REGION_A \
  --set-env-vars="ENV=production"

Traffic gradually returns to africa-south1 as instances pass their readiness probes and Service Health transitions back to HEALTHY.

Safe rollout strategy using readiness probes

One of the most powerful features of the new readiness probe model is the ability to do canary deployments across regions with automatic rollback via Service Health.

The official recommended rollout process:

# Step 1: Deploy new revision to ONE region with 1% traffic
gcloud run deploy $SERVICE \
  --image=$IMAGE_NEW \
  --region=$REGION_A \
  --readiness-probe="httpGet.path=/health" \
  --min=1 \
  --no-traffic  # Deploy but send no traffic yet

# Step 2: Send 1% of traffic to new revision in REGION_A only
gcloud run services update-traffic $SERVICE \
  --region=$REGION_A \
  --to-revisions=LATEST=1

# Step 3: Monitor readiness metric
# run.googleapis.com/container/instance_count_with_readiness
# If this stays healthy, continue increasing traffic

# Step 4: Ramp to 100% in REGION_A
gcloud run services update-traffic $SERVICE \
  --region=$REGION_A \
  --to-revisions=LATEST=100

# Step 5: Once REGION_A service_health_count is stable HEALTHY,
# deploy to REGION_B
gcloud run deploy $SERVICE \
  --image=$IMAGE_NEW \
  --region=$REGION_B \
  --readiness-probe="httpGet.path=/health" \
  --min=1

If the new revision's readiness probes fail in REGION_A, Service Health marks that region unhealthy, the load balancer routes traffic to REGION_B (still running the old revision), and you have automatic rollback without a single manual step.

Known limitations of Service Health (GA)

The official documentation lists several limitations worth knowing before you build:

Minimum instances required. You must configure at least one minimum instance per region for Service Health to calculate health. A region with zero running instances cannot report health, which means a cold-start region cannot participate in automatic failover.
Minimum two regions. Failover requires at least two services from different regions. If you only deploy to one region and it fails, the load balancer returns no healthy upstream.
Max 5 NEG backends for cross-region internal LB. The limitation applies to the internal load balancer variant, not the global external LB.
No URL masks or tags in Serverless NEGs. If your routing requires URL masks, you cannot use Service Health's NEG model.
No IAP from the backend service. If you need Identity-Aware Proxy, configure it directly on the Cloud Run service, not at the load balancer backend.
First probe on new instances. A newly started instance will not have its first readiness probe counted before it begins receiving traffic. This means a very brief window where traffic may route to an instance before it has confirmed readiness.
Revisions without probes are treated as unknown. The load balancer treats unknown health as healthy, so if you deploy a revision without a readiness probe configured, it will receive traffic regardless.

The last two points are important for zero-downtime deployments. The recommended safe rollout process (canary in one region before the other) directly addresses both.

What this architecture does not solve

Database availability. Compute-layer failover is irrelevant if your Cloud Run service connects to a single-region Cloud SQL instance. The database tier needs its own HA: Cloud SQL cross-region read replicas, Cloud Spanner for global consistency, or Firestore in Native mode (inherently multi-region).

Stateful sessions. Cloud Run is stateless. Cross-region routing will invalidate in-memory sessions. Use Cloud Memorystore (Redis) or stateless JWT-based sessions.

Data residency. Routing traffic across regions may conflict with NDPR, GDPR, or sector-specific regulations. Know your data residency obligations before deploying multi-region.

Pub/Sub push subscriptions. By default, Pub/Sub delivers messages to push endpoints in the same region where it stores the messages. A multi-region Cloud Run setup behind a global LB does not automatically receive Pub/Sub push traffic from all regions. The official docs provide a workaround, review the Pub/Sub multi-region push documentation before building event-driven architectures on this pattern.

From Apple Health Data to Clinical Storytelling: Building an AI-Powered Report with Python and Gemini

Romina Elena Mendez Escobar — Mon, 20 Jul 2026 09:55:58 +0000

Introduction

At recent technology conferences, one topic has caught my attention: every year, more health-focused devices, sensors, and applications appear. Smartwatches track heart rate, smart scales measure body data, glucose monitors record blood sugar levels, and apps help users track sleep or nutrition. Today, the amount of information we can collect about our own bodies is enormous.

This article was inspired by an everyday experience with my father, Herminio ❤️. Whenever he has a medical appointment, he opens the Apple Health app and shows the doctor the evolution of his heart rate, physical activity, sleep hours, and other recorded metrics.

While watching this, I kept asking myself the same question: are we really making the most of all this information?

Showing a chart during a medical appointment can be useful, but the data could provide much more value if it were automatically processed, summarized, and transformed into a structured health report.

For this reason in this project, I use Gemini to transform previously calculated metrics into a clear and organized summary. The LLM does not analyze all the raw records or perform the main calculations. The pipeline processes the data, calculates the indicators, and generates the visualizations, while the model acts as a support layer for building the report narrative.

The goal is not to create a medical application or replace professional judgment. Instead, the purpose is to build a prototype that shows how Apple Health exports, deterministic data processing, visualizations, and an LLM can be combined to generate automated reports.

This project was developed using simulated data from three patients, so the complete pipeline can be reproduced without using real clinical information.

✨ Why Gemini?

This project uses an LLM to transform previously processed metrics into a structured narrative that can be reviewed more easily by a healthcare professional.
I chose Gemini for practical reasons:

〰️ I was already familiar with its API, it integrates easily with Python, and Google AI Studio makes it simple to test and adjust prompts.
〰️ It also offers a good balance between speed, performance, and cost for text-generation tasks.
〰️ Its free tier also makes it easier to reproduce this MVP without initial costs.

In this case, I use a general-purpose model because all calculations are completed in Python before the data is sent to Gemini. The model only organizes the results into readable text.
For projects that need to analyze clinical documents or medical images directly, specialized models such as MedGemma could also be evaluated. MedGemma is a family of open Google models adapted for healthcare-related tasks. However, its implementation, evaluation, and validation are outside the scope of this tutorial.

2. HealthKit: The Framework Behind the Data

Although most users only interact with the Apple Health app, HealthKit is the framework behind it. Apple provides HealthKit so developers can securely access health information stored on the device.

HealthKit works as a central repository where the iPhone and Apple Watch store health and fitness data. With the user’s explicit permission, authorized applications can read and write information through a single API. This avoids the need for every app to maintain its own separate database.

HealthKit currently supports hundreds of data types across many areas of health and well-being. The following figure presents a simplified grouping of some of these categories to provide a clearer overview of the available information.

This taxonomy was created specifically for this article based on publicly available HealthKit documentation. It is not an official Apple classification and should be understood as a summarized, author-created interpretation for explanatory purposes.

Thanks to this architecture, HealthKit makes it possible to:

Collect and store health and fitness information.
Analyze and visualize how this data changes over time.
Share information between authorized applications, reducing duplication and enabling new user experiences.

One of the most interesting design decisions in HealthKit is its large catalog of predefined classes and data types for standardized health metrics.

At first, this may seem restrictive for developers. However, it is actually one of the platform’s main strengths because it ensures that all stored information follows a consistent data model. This means that heart rate, blood glucose, or body weight always represent the same type of information and use the same units, regardless of the device or application that created the record.

This standardization simplifies application development, improves interoperability between apps, and helps maintain consistency across the data stored in HealthKit.

2.1 Data Sources

One of HealthKit’s main benefits is its ability to bring data from multiple sources into a single repository.
The most common sources include:

iPhone: records steps, distance traveled, mobility data, and other indicators collected through its sensors.
Apple Watch: provides physiological metrics such as heart rate, electrocardiogram (ECG), blood oxygen saturation (SpO₂), body temperature, sleep data, workouts, and cardiorespiratory fitness (VO₂ Max).
Third-party apps: can add information related to nutrition, mental health, hydration, medication, menstrual cycles, or sports training.
Connected medical devices and wearables: HealthKit supports Bluetooth Low Energy (BLE) health devices and medical data profiles. It can also work with FHIR (Fast Healthcare Interoperability Resources), making it possible to integrate data from devices such as glucose meters and blood pressure monitors, as well as clinical records from authorized healthcare institutions.

3. HL7 / FHIR Compatibility

So far, we have mainly discussed data generated by devices and applications. However, in 2018 Apple expanded the Health app by introducing Health Records, a feature that allows users to import structured clinical information from supported healthcare institutions. That same year, Apple also opened access to these records for authorized applications through the HealthKit API.

Health Records is built on HL7 FHIR, which stands for Fast Healthcare Interoperability Resources. FHIR is a standard developed by HL7 International to represent and exchange health information electronically between hospitals, applications, and Electronic Health Record systems.

FHIR organizes information into modular resources such as Patient, Observation, Condition, Procedure, MedicationRequest, and Immunization. Each resource represents a specific piece of clinical information that can be connected, queried, and exchanged between systems. Although FHIR can also be used to build clinical documents, its architecture does not require the entire patient record to be handled as one large document.

When records are downloaded from a supported institution, HealthKit represents each one as an HKClinicalRecord object, which keeps the original FHIR resource. Authorized applications can request the clinical record types they need and process their content as FHIR JSON. However, these records are read-only, which means applications cannot create new HKClinicalRecord objects or modify existing ones.

Access to any HealthKit information requires user consent, but clinical records have additional requirements because of their sensitivity. An application must enable the Clinical Health Records capability, include the required entitlement, explain why the information is needed, and request permission for each record type it wants to access. The use of this capability is also subject to Apple’s review process.

In HealthKit, clinical records are represented as read-only HKClinicalRecord objects that preserve the original FHIR content. Access requires explicit user authorization and is subject to additional privacy and platform requirements.

This architecture makes it possible to bring together information from different sources while keeping access centered on user consent and privacy.

4. HealthKit: Clinical Use Cases

The availability of large volumes of physiological data, combined with interoperability standards such as FHIR, has created many opportunities for research and clinical applications.

The value of this data does not come only from individual measurements, but from how they are analyzed over time. Tracking changes in heart rate, sleep, mobility, or activity levels can help identify patterns, summarize relevant information, and support patient monitoring in different healthcare scenarios.

The following figure presents some representative use cases, including early anomaly detection, remote patient monitoring, clinical summary generation, and synthetic data generation for research.

5. Technical, Clinical, and Regulatory Considerations

Before running the tutorial or using the code presented in this article, it is important to understand its scope and consider several limitations related to privacy, data quality, and the use of artificial intelligence in healthcare contexts.

5.1 Privacy and Data Protection

Health information is one of the most sensitive categories of personal data. Depending on the country and the context of use, it may be subject to regulations such as HIPAA in the United States or GDPR in the European Union.

Although this article uses only simulated data, any implementation that processes real information should include suitable controls for:

User consent.
Access management.
Data minimization.
Anonymization or pseudonymization.
Encryption.
Secure storage and processing.

5.2 Consumer Data Is Not a Diagnosis

Measurements collected through consumer devices can provide useful information for identifying trends and supporting long-term monitoring.
However, these records do not represent a medical diagnosis on their own and should not replace measurements taken with certified clinical equipment.

5.3 Data Quality and Continuity

The quality of the measurements can be affected by factors such as incorrect device placement, low battery levels, synchronization failures, periods when the device is not used, or differences between sensors and applications.
These situations may produce:

Incomplete records.
Duplicate measurements.
Outliers.
Periods with missing information.
Differences in units or sampling frequency.

For this reason, the data should be validated, cleaned, and normalized before generating any analysis. It is also important to identify periods where the available information is not complete enough to support reliable conclusions.

5.4 Use and Limitations of the LLM

In this project, the large language model does not diagnose conditions or recommend treatments. Its role is to transform previously calculated metrics into a clear and structured summary that can be reviewed more easily by a healthcare professional.

Any generated output should be treated as a draft that requires human review. The model may omit information, misunderstand a result, or produce statements that are not fully supported by the input data.

5.2 Scope of the Code

The repository provided with this article should be understood as an educational and experimental MVP. It is designed to demonstrate the general processing flow using simulated data.

It is not a medical product, a diagnostic tool, or an implementation ready for direct use in a clinical environment.
Before adapting the code to a real use case, additional validation would be required in areas such as:

Security and access control.
Error handling and traceability.
Data quality and provenance.
Reproducibility of the results.
Evaluation of the model’s responses.
Compliance with applicable standards and regulations.
Review and approval by qualified professionals.

The goal of this project is to present one possible architecture and explore its main components, not to provide a production-ready clinical solution.

6. Building the Apple Health Reporting Pipeline

In this tutorial, we will build a Python pipeline that processes an Apple Health XML export and generates a structured PDF report.
The pipeline will:

read and normalize the exported health records;
calculate mobility, cardiovascular, and sleep metrics;
compare the results against configurable reference values;
generate charts;
use Gemini to create a structured narrative;
combine everything into a final PDF report.

The generated report contains four main sections:

🚶 Mobility: daily steps, walking speed, steadiness, gait metrics, and caloric expenditure.
❤️ Cardiovascular: resting heart rate, HRV, oxygen saturation, VO₂ Max, and recovery metrics.
😴 Sleep: average sleep duration and nights above or below the configured references.
🤖 AI-generated summary: a structured narrative with patient profile, mobility, cardiovascular, sleep, and overall assessment sections.

The following diagram shows the complete flow of the project:

The implementation follows a modular architecture in which each class is responsible for one stage of the pipeline:

📥 HealthDataReader reads and processes the Apple Health export.
📊 HealthChartBuilder generates the visualizations.
✨ HealthSummaryGenerator creates the narrative using Gemini.
📄 HealthReportPDF combines the metrics, charts, and generated text into the final report.

In the next sections, we will review each stage separately. To keep the article focused, I will only include the most relevant code fragments and design decisions. The complete implementation, configuration files, prompt template, and simulated data are available in the project repository.

6.1 Prerequisites

To follow the tutorial, you will need:

The project repository cloned locally.
An Apple Health XML export or one of the simulated files included in the repository.
A Gemini API key created from Google AI Studio.
The Python dependencies installed from the project requirements.txt file.

You can clone the repository and install the dependencies with:

RominaElenaMendezEscobar / apple-health-data

Python pipeline that processes Apple Health XML exports, calculates health metrics, generates visualizations, creates a structured narrative with Gemini, and builds a final PDF report using simulated patient data.

From Apple Health Data to Clinical Storytelling: Building an AI-Powered Report with Python and Gemini

Apple Health Reporting Pipeline with Python and Gemini

A modular Python pipeline that processes Apple Health XML exports, calculates health metrics, generates visualizations, creates an AI-assisted narrative with Gemini, and builds a structured PDF report.

This repository is an educational MVP built with simulated data. It is not a medical device, diagnostic tool, or production-ready clinical solution.

Overview

The pipeline:

Reads and normalizes Apple Health XML records.
Calculates mobility, cardiovascular, and sleep metrics.
Compares results with configurable reference values.
Generates charts with Matplotlib.
Creates a structured narrative with Gemini.
Combines metrics, charts, and text into a PDF report.

HealthKit: The Framework Behind the Data

HealthKit is Apple’s framework for storing and sharing health and fitness information collected by the iPhone, Apple Watch, third-party apps, and compatible devices.

It provides standardized data types for metrics such…

View on GitHub

✨Gemini API key
You can create an API key from Google AI Studio.
After creating it, add a .env file at the root of the project:

gemini_api_key=YOUR_CREDENTIAL

6.2 Data source

Apple Health allows users to export their information as a ZIP file containing an XML document.

The export can be generated from the Health app:

Open the Health app on the iPhone.
Tap the profile icon.
Select Export All Health Data.
Confirm the export.
Extract the generated ZIP file.

The tutorial uses the export.xml structure produced by this process. However, to avoid exposing real health information, the repository includes three simulated patient files:

alex_28m.xml: 28-year-old male patient.
carlos_68m.xml: 68-year-old male patient.
maria_61f.xml: 61-year-old female patient. These files are stored in the patients/ folder and allow the complete pipeline to be reproduced without using real clinical data.

6.3 Orchestrating the Pipeline

The complete project is coordinated from the main.py file, which works as the application entry point. Its responsibility is not to process the data directly, but to create the specialized classes and execute each stage of the pipeline in the correct order.

This file also defines the list of patients to be processed. For each patient, it includes the XML file path and the name that will appear in the final report. The files are declared explicitly to make the example easier to follow, although a more general implementation could discover them automatically from a folder.

The complete main.py file is shown below:

from healthChartBuilder import HealthChartBuilder
from healthDataReader import HealthDataReader
from healthReportPDF import HealthReportPDF
from healthSummaryGenerator import HealthSummaryGenerator
import utils
import os

if __name__ == "__main__":
   patients = [
       ("patients/alex_28m.xml",   "Alex Torres"),
       ("patients/maria_61f.xml",  "María González"),
       ("patients/carlos_68m.xml", "Carlos Mendez"),
   ]

   os.makedirs("reports", exist_ok=True)
   os.makedirs("charts",  exist_ok=True)
   os.makedirs("data",    exist_ok=True)

   env = utils.read_env()

   for xml_path, name in patients:
       print(f"\n── {name} ──")
       prefix = name.lower().replace(' ', '_')

       # Step 1: read and compute
       reader = HealthDataReader(xml_path).load()

       # Step 1.1: save the compact LLM-friendly summary for this patient
       reader.save(write_llm_summary=True, file_name=prefix)

       # Step 2: generate charts
       builder = HealthChartBuilder(
           metrics    = reader.metrics,
           output_dir = "charts",
           prefix     = prefix,
       )
       charts = builder.build_all()

       # Step: generate the narrative summary with Gemini
       generator = HealthSummaryGenerator(
           json_path   = f"data/{prefix}_llm_summary.json",
           yml_path    = "config/params_health.yml",
           prompt_path = "prompt/prompt_summary.txt",
           api_key     = env["gemini_api_key"],
       ).load()
       llm_text = generator.generate()

       # Step 3: build PDF
       HealthReportPDF(
           metrics        = reader.metrics,
           charts         = charts,
           patient_name   = name,
           date_of_birth  = reader.date_of_birth,
           biological_sex = reader.biological_sex,
           start_date     = reader.df['start'].min(),
           end_date       = reader.df['start'].max(),
           out_path       = f"reports/{prefix}_report.pdf",
           llm_summary    = llm_text,
       ).build()

6.4 Reading and Processing the Apple Health Export

The HealthDataReader class reads the XML file exported from Apple Health and transforms it into a structure that can be analyzed with Python. During this process, it extracts the available records, normalizes dates and numeric values, limits the analysis to the configured period, and calculates the metrics used by the next stages of the pipeline.

The class receives the XML file path and, optionally, the number of months to include in the analysis:

reader = HealthDataReader( 
xml_path="patients/alex_28m.xml", months=6, 
).load()

The load() method runs two main operations:

📥 _parse_xml() reads the file, extracts the records, and transforms them into a Pandas DataFrame.
📐 _compute_metrics() calculates the daily series and aggregated indicators used in the analysis.

Threshold Configuration

The values used to classify or compare the metrics are not hardcoded inside the class. Instead, they are loaded from config/params_health.yml.

This separation makes it possible to update the reference values without changing the Python implementation:

threshold_steps_low:
  description: Step count threshold for red zone.
  value: 3000
threshold_steps_mid:
  description: Step count threshold for orange zone.
  value: 5000
threshold_steps_goal:
  description: Step count goal line.
  value: 7000
threshold_speed_low:
  description: Walking speed considered critically low.
  value: 3.5
threshold_speed_goal:
  description: Walking speed reference value.
  value: 4.5
threshold_steadiness:
  description: Steadiness warning value.
  value: 0.60
threshold_spo2_low:
  description: SpO2 critical threshold.
  value: 95.0
threshold_spo2:
  description: Minimum SpO2 reference value.
  value: 96.0
threshold_sleep_min:
  description: Sleep duration for red zone.
  value: 5.0
threshold_sleep_mid:
  description: Sleep duration for orange zone.
  value: 6.0
threshold_sleep_goal:
  description: Sleep duration goal.
  value: 7.0
threshold_hrv:
  description: Minimum HRV reference value.
  value: 25.0

These parameters affect several parts of the project. They are used, for example, to calculate how many days fall below a specific step count, identify periods of low walking speed, evaluate sleep duration, and define the reference zones later used in the charts and the final report.

⚠️ Note: The values included in the repository are only for demonstration and are intended to support the example with simulated data. They should not be treated as clinical criteria. Before adapting the code to a real use case, the thresholds should be reviewed and validated by healthcare professionals, considering the population, age group, clinical context, and specific purpose of the solution.

Metric Selection

The _compute_metrics() method defines which data types are processed and which indicators are calculated. In the current implementation, the metrics are mainly organized into three groups:

🚶 Mobility and activity: steps, walking speed, step length, steadiness, asymmetry, active energy, and flights climbed.
❤️ Cardiovascular: resting heart rate, HRV, oxygen saturation, respiratory rate, VO₂ Max, and heart rate recovery.
😴 Sleep: daily duration, average sleep, and the number of nights below or above the configured thresholds. The daily series are calculated using sums or averages, depending on the type of record:

steps = self._daily_sum("StepCount")
speed = self._daily_mean("WalkingSpeed")
hr = self._daily_mean("RestingHeartRate")
hrv = self._daily_mean("HeartRateVariabilitySDNN")
spo2 = self._daily_mean("OxygenSaturation")

⚠️ Note: The thresholds are not the only values that should be reviewed. It is also important to confirm that the statistical methods used by the class are appropriate for each metric. For example, the mean can be affected by outliers. Before using this approach in production, other measures such as the median or percentiles may need to be evaluated.

Preparing the Data for the LLM

In addition to the full set of metrics, the class generates a smaller JSON file through to_llm_summary().
Instead of sending the complete time series, Python creates a compact and deterministic representation that includes:

📊 mean and standard deviation;
↕️ minimum and maximum values;
📈 trend over the analysis period;
📅 best and worst weekly averages;
🔄 weekly variability;
⏱️ longest consecutive period below the configured threshold.

Not every metric includes all of these fields, because some calculations do not apply in the same way to every type of data. This decision has two main benefits:

1. Reducing the amount of data sent to the model. An Apple Health export may contain thousands of records. Sending all observations would increase the prompt size, token usage, and execution cost, while also adding repetitive information that may not improve the final summary.
2. Keeping the calculations in Python. Averages, trends, minimum and maximum values, weekly statistics, and threshold streaks are calculated in advance using deterministic code. The LLM receives fixed and verifiable values and is only responsible for turning them into a natural-language summary.

This separation also makes the project easier to maintain. If the trend calculation changes or a new metric is added, the update can be made in Python without changing the role of the language model.
For example, the model receives a structure like this:

{
  "steps": {
    "mean": 9498.53,
    "std": 1728.37,
    "min": 5667.0,
    "max": 14201.0,
    "trend": "stable",
    "worst_week_mean": 8214.29,
    "best_week_mean": 10672.71,
    "weekly_volatility": 576.09,
    "worst_streak_below_threshold": 0
  }
}

6.5 Generating Clinical Charts

The HealthChartBuilder class receives the metrics calculated by HealthDataReader and generates the charts that are later included in the final report.
To keep the presentation logic separate from the data-processing logic, the class uses two configuration files:

🎯 params_health.yml: defines the reference thresholds used for color zones and horizontal lines in each chart.
🎨 params_styles.yml: stores the color palette applied consistently across all visualizations.

Generated Charts

The build_all() method coordinates the chart-generation process and delegates each visualization to an independent private method:

🚶 Activity and mobility — _chart_steps(), _chart_mobility(), and _chart_calories(): daily steps with threshold-based color zones, walking speed with a reference line, and active versus basal calories.
❤️ Cardiovascular — _chart_hrv() and _chart_spo2(): heart rate variability with a minimum reference value, and oxygen saturation with critical, low, and normal zones.
😴 Sleep — _chart_sleep(): nightly sleep duration displayed with threshold-based color zones. If no sleep data is available, the chart shows an alternative message. Each chart is implemented independently, so it can be modified or replaced without affecting the rest of the pipeline.

6.6 Generating the Narrative with Gemini

The HealthSummaryGenerator class receives the summary created by HealthDataReader and uses Gemini to transform it into structured natural-language text. At this stage, the original Apple Health records are not sent to the model. Instead, Gemini receives the metrics that were already calculated and summarized in the previous step.
To build the prompt, the class uses three input files:

📊 json_path: contains the patient’s compact summary, including the previously calculated metrics and statistics.
🎯 yml_path: points to params_health.yml, which contains the thresholds used to compare each metric.
📝 prompt_path: contains the prompt template and the instructions the model must follow. The load() method reads these files and initializes the Gemini client:

self.datos = utils.read_json_file(self.json_path)
self.yml = utils.read_yml_file(self.yml_path)
self.prompt = utils.read_txt_file(self.prompt_path)
self.client = genai.Client(api_key=self.api_key)

Prompt Structure

The prompt template defines how the report should be generated. Instead of including the complete prompt in the article, its main instructions can be summarized as follows:

🧭 Patient context: calculates the patient’s age from the date of birth and considers biological sex and the analysis period.
📐 Threshold comparison: defines which value from params_health.yml should be used to evaluate each metric.
📑 Report structure: requires fixed sections for patient profile, mobility, cardiovascular data, sleep, and overall assessment.
🔎 Trends and continuity: asks the model to consider metric trends, weekly variability, and consecutive periods below the configured thresholds.
🚫 Restrictions: prevents the model from inventing data, using unavailable fields, or making general judgments about the patient’s health. It also avoids subjective terms such as “healthy” or “concerning.” The model should only report whether each value is above, within, or below its corresponding threshold.

This last point is especially important, because the model should describe the available values and their relationship to the configured thresholds without making a diagnosis or turning the summary into medical advice.

Building and Running the Prompt

The class separates prompt preparation from the model call:

_build_prompt()replaces the {datos} and {yml} placeholders with the actual JSON data and threshold configuration.
generate() sends the completed prompt to Gemini and returns the generated text.

prompt = self._build_prompt()

response = self.client.models.generate_content(
    model=self.model_id,
    contents=prompt,
    config=types.GenerateContentConfig(
        max_output_tokens=self.max_tokens,
        thinking_config=types.ThinkingConfig(
            thinking_budget=0
        ),
    ),
)

6.7 Generating the Final PDF Report

The HealthReportPDF class combines the results produced during the previous stages and creates the final PDF report using ReportLab.
The class receives four main inputs:

📊 Metrics and KPIs: obtained directly from the metrics dictionary generated by HealthDataReader. The class does not recalculate the main statistics. Instead, it organizes them into KPI cards, tables, alerts, and short descriptions.
📈 Charts: receives the image paths generated by HealthChartBuilder and adds each chart to the corresponding report section.
✨ Gemini summary: receives the narrative generated by HealthSummaryGenerator and includes it as a separate section.
🎯 Configuration: uses params_health.yml and params_styles.yml to apply the same thresholds and visual styles used across the rest of the pipeline.

This class does not calculate averages, trends, or weekly statistics. Those values are already produced by HealthDataReader. It only performs simple comparisons against the configured thresholds to decide whether a table should display a ✓ or ⚠ status and whether an alert should be added to the report.

Report Structure

The generated document is divided into four sections:

🚶 ① Mobility: KPIs for steps, walking speed, steadiness, gait asymmetry, and activity, together with the related charts and reference tables.
❤️ ② Cardiovascular: resting heart rate, HRV, SpO₂, VO₂ Max, and recovery metrics. This section is adapted when Apple Watch data is not available.
😴 ③ Sleep: average sleep duration, nights below the minimum threshold, and nights that meet the configured goal.
🤖 ④ AI-Generated Summary: the narrative generated by Gemini, converted from simple Markdown into formatted PDF content.

Alerts and Reference Status

Before building the report sections, the build() method checks the main metrics against their configured thresholds.

For example, it can generate an alert when:

the average number of steps is below the target;
walking speed is below the reference value;
HRV or SpO₂ is below the configured threshold;
average sleep duration does not meet the expected value. These alerts are based on simple comparisons and do not represent medical diagnoses.

AI Disclaimer

The AI-generated section always includes a visible disclaimer. It explains that the text was created from device data, is not a clinical evaluation or diagnosis, and may contain errors or incorrect interpretations.
The disclaimer also reminds the reader that the generated narrative should be checked against the original metrics and reviewed by a qualified professional before being used in any health-related decision.

7. Conclusions

One of the main challenges of this project was transforming Apple Health records into useful and understandable information. HealthKit’s consistent data structure makes this processing easier and supports the creation of a reusable pipeline. It also opens the door to interoperability: in a real environment, representing the results with standards such as HL7 FHIR could simplify their exchange with applications, hospitals, and electronic health record systems.

Separating Calculation from Interpretation

A relevant design decision was to keep the calculations in Python and use Gemini only to generate the narrative. Averages, trends, threshold comparisons, and weekly statistics are calculated in a controlled way, while the model receives already processed values and turns them into readable text.
Summarizing the data before sending it to the LLM also reduces token usage, execution cost, and the risk of reaching the context window limit. This approach provides more control over the information used to generate the report.

Personalization and Data Quality

The same metrics and thresholds are not suitable for every patient or every use case. Making these values configurable allows the analysis to be adapted to the patient profile, the monitoring objective, and the specific needs of the project.
However, configuration alone does not guarantee reliable results. The statistical methods should also be validated, and the pipeline should measure data completeness. For example, it should be able to distinguish between a real reduction in activity and missing records caused by low battery, synchronization problems, or irregular device use.
In a real implementation, metrics, thresholds, and validation rules should be reviewed together with healthcare professionals.

Security and Responsible Data Use

Health data requires specific controls for privacy, access, storage, and retention. A real solution should define what information is collected, who can access it, how long it is stored, and which data may be sent to external services.
Although these topics are outside the scope of this article, they should be considered from the beginning of the design process. Consent, data minimization, and retention policies should not be added only after the technical implementation is complete. This principle is also reflected in Apple Health, which requires explicit permission to read and write health information.

Final Note

This project is an educational MVP built with simulated data. It is not ready for production and should not be used directly to make health-related decisions.
Its main purpose is to demonstrate how continuous health data, deterministic processing, visualizations, and a language model can be combined in a modular pipeline. The LLM can help communicate the results, but the calculations, validation rules, and data-quality controls should remain reproducible and verifiable.

8. 📚 Reference

Apple. (2018, 24 de enero). Apple announces solution bringing health records to iPhone. Apple Newsroom. https://www.apple.com/newsroom/2018/01/apple-announces-effortless-solution-bringing-health-records-to-iPhone/
Apple. (2020). Handling FHIR without getting burned [Video]. Apple Developer. https://developer.apple.com/videos/play/wwdc2020/10669/
Apple. (s. f.). Accessing Health Records. Apple Developer Documentation. Retrieved July 10, 2026, from https://developer.apple.com/documentation/healthkit/accessing-health-records
Apple. (s. f.). Configuring HealthKit access. Apple Developer Documentation. Retrieved July 10, 2026, from https://developer.apple.com/documentation/xcode/configuring-healthkit-access
Apple. (s. f.). HealthKit. Apple Developer Documentation. Retrieved July 10, 2026, from https://developer.apple.com/documentation/healthkit
Google. (2026, 23 de junio). Gemini 2.5 Flash. Google AI for Developers. https://ai.google.dev/gemini-api/docs/models/gemini-2.5-flash
Google. (s. f.). Guía de inicio rápido de Google AI Studio. Google AI for Developers. Retrieved July 10, 2026, from https://ai.google.dev/gemini-api/docs/ai-studio-quickstart?hl=es-419
Google. (s. f.). MedGemma 27B instruction-tuned model card. Hugging Face. Retrieved July 10, 2026, from https://huggingface.co/google/medgemma-27b-it
Health Level Seven International. (2023, 26 de marzo). FHIR overview: FHIR release 5. https://fhir.hl7.org/fhir/overview.html
Health Level Seven International. (2023, 26 de marzo). Introducing HL7 FHIR: FHIR release 5. https://fhir.hl7.org/fhir/summary.html

How My AI Agent Hacked Its Own Permissions (And What It Taught Me)

Alexander Tyutin — Tue, 23 Jun 2026 17:09:18 +0000

Have you ever tried to build an automation that works so well it bypasses the very rules you set for it? Recently, I was working on a small repository designed to automate the painful process of updating my resume. The idea was simple: build a system that runs weekly, checks my social media activity, and proposes updates to my CV, complete with a fresh branch and a diff ready for my review every Monday morning. You can check out the repository here: https://github.com/tyutinalexkz/cv

I used an AI agent to do the heavy lifting. As a developer who values security, I configured the agent with no default command execution permissions. Step-by-step, I granted it specific capabilities for in-repo file management. It worked perfectly.

But then, I got ambitious.

Once the workflow was tested, I asked the agent to configure its own environment to perform this flow silently every week. I essentially said, "Make this run automatically without asking me."

The agent attempted to change its permissions, but hit a wall - it didn't have the explicit authorization to modify the workspace configuration directly. A normal script would throw an error and stop. But this was a thinking model.

It looked at the list of commands I had already allowed it to use. It saw standard file manipulation tools. And then, it compiled a chain of commands - specifically using cp and jq - to manipulate its own configuration files. By doing so, it effectively granted itself the new capabilities it needed, bypassing the standard configuration flow and its limitations!

I just sat there, laughing. I was observing it as a developer, seeing how easy it could be to live without security barriers if you know the right tools. But the underlying lesson was profound. Even a helpful, non-malicious AI, when given a goal and a subset of seemingly harmless tools, will find creative ways to achieve that goal - even if it means escalating its own privileges.

If we give an agent to a user in a corporate setting, it might seem safe if we restrict its primary permissions. But as my little experiment showed, an agent with basic file manipulation tools and problem - solving skills can easily find a workaround. The future of AI safety isn't just about what an agent is explicitly allowed to do; it's about what it can piece together from the tools it has.

Securely Exposing Internal GCP VMs using Cloudflare Tunnels

Alexander Tyutin — Tue, 16 Jun 2026 06:07:42 +0000

Exposing a web service to the public internet typically involves assigning a public IP address to the Virtual Machine, opening firewall ports (e.g., 80/443), and configuring TLS certificates. However, this traditional approach leaves the infrastructure vulnerable to port scanning, DDoS attacks, and zero-day exploits.

A more modern, secure, and elegant approach is to use a Cloudflare Tunnel (cloudflared) combined with a GCP VM that has no external IP address.

This article explains the architecture, security benefits, step-by-step implementation, and troubleshooting for this approach.

1. The Architecture

Instead of accepting incoming connections (Ingress), the cloudflared daemon runs on the VM and establishes an outbound-only, encrypted, long-lived QUIC connection to the Cloudflare Edge network.

When a client visits the configured domain, Cloudflare proxies the request through this established tunnel directly to the internal service.

Benefits of this architecture

No Ingress Firewall Rules: There is no need to open port 80 or 443 in the GCP VPC firewall.
No Public IP: The VM is invisible to the public internet. It cannot be pinged or port-scanned.
Automatic SSL/TLS at the Edge: While end-to-end encryption (HTTPS everywhere) is advocated as a best practice, this guide configures the internal traffic between cloudflared and the target service as plain HTTP for simplicity. Cloudflare handles the public-facing HTTPS certificates automatically, simplifying the initial setup.
Out-of-the-box DDoS Protection: Cloudflare absorbs volumetric attacks before they ever reach the GCP infrastructure.

2. GCP VM Security Measures

When designing a secure VM without an external IP, the following GCP-specific security measures should be implemented:

A. Networking (Cloud NAT)

Since the VM has no public IP, it cannot access the internet directly. However, cloudflared needs internet access to connect to Cloudflare, and the VM needs internet to pull updates or Docker images.

Solution: Set up a Cloud Router and Cloud NAT in the VPC. This allows outbound internet access for internal VMs while blocking all inbound internet connections.

B. Shielded VM Features

Enable Shielded VM options to protect the boot process and kernel integrity:

Secure Boot: Ensures the system only boots authentic, digitally signed software.
vTPM (Virtual Trusted Platform Module): Validates the VM's identity and provides secure key generation.
Integrity Monitoring: Generates alerts if the boot sequence is tampered with.

C. Identity and API Access

Dedicated Service Account: Avoid using the default Compute Engine service account. Create a custom service account with the absolute minimum permissions required.
Metadata Security: Ensure disable-legacy-endpoints = true in the instance metadata to prevent Server-Side Request Forgery (SSRF) attacks from extracting GCP credentials from the metadata server.

D. Secure SSH Access (IAP)

Since there is no public IP, standard SSH over the internet is impossible.

Solution: Use Identity-Aware Proxy (IAP) TCP Forwarding. IAP validates Google Identity and IAM permissions before tunneling the SSH connection through GCP's internal backbone to the VM.

3. Step-by-Step Implementation

Step 1: Provisioning the Cloudflare Tunnel

Navigate to the Cloudflare Zero Trust Dashboard -> Networks -> Tunnels.
Create a new tunnel and select Cloudflared.
Add a Public Hostname (e.g., app.example.com) and point it to the internal service (http://webapp:8080).
Copy the generated Tunnel Token.

Step 2: Infrastructure Configuration (Docker Compose)

Docker Compose can be used to run both the service and the cloudflared daemon in the same isolated bridge network.

version: '3.8'

services:
  webapp:
    image: your-company/webapp:latest
    restart: always
    environment:
      - APP_ENV=production
      # Listen on all interfaces inside the container, but expose NO ports to the host
      - LISTEN_ADDRESS=0.0.0.0

  cloudflared:
    image: cloudflare/cloudflared:latest
    restart: always
    # CRITICAL: Prevent zombie processes by running tini as PID 1
    init: true
    command: tunnel --no-autoupdate run
    environment:
      - TUNNEL_TOKEN=your_secret_token_here
    depends_on:
      - webapp

Note: Notice there is no ports: ["8080:8080"] mapped to the host. The cloudflared container reaches the web app entirely within the internal Docker network via http://webapp:8080.

Step 3: Run the stack

docker-compose up -d

Within seconds, cloudflared will connect to the Cloudflare Edge, and the site will be securely accessible.

4. Diagnostics & Troubleshooting

When diagnosing connectivity issues, the non-standard traffic flow requires a systematic approach.

A. Diagnosing the Edge (Cloudflare)

A 502 Bad Gateway error indicates that Cloudflare Edge cannot reach the cloudflared tunnel, OR cloudflared cannot reach the target container.

# Check the HTTP response from the outside
curl -I https://app.example.com

B. Diagnosing the Host & Services

Before diving into logs, verify the overall health and resource consumption of the host and Docker containers.

# Check container uptime, status, and IDs
sudo docker ps -a

# Check memory and CPU usage (crucial for diagnosing OOM freezes)
sudo docker stats --no-stream

# Look for stray processes outside of Docker
sudo ps aux | grep cloudflared
sudo systemctl status webapp.service

C. Diagnosing the Tunnel (Cloudflared)

Verify that cloudflared is running and successfully connected to the Edge:

sudo docker logs --tail 50 <cloudflared_container_id>

Look for: INF Registered tunnel connection or ERR Unable to reach the origin service.

D. Verifying Internal Docker Connectivity

Verify that the service is actually alive and responding to the tunnel's requests. Simulate the tunnel's behavior by running a temporary curl container inside the same Docker network:

# Replace 'app_default' with the actual docker network name
sudo docker run --rm --network app_default curlimages/curl -s -I -m 5 http://webapp:8080

If this returns 200 OK, the service is healthy, and the issue lies in the Tunnel or Cloudflare configuration.

5. Common Failures & Edge Cases

[!WARNING]
The Zombie Process (Duplicate Connectors)
When updating or restarting containers (docker-compose down && docker-compose up), Docker sends a SIGTERM to cloudflared. Occasionally, the process ignores the signal, and Docker forcefully orphans it. The process remains alive in the host OS's memory, continuing to send keep-alives to Cloudflare.

Symptom: Cloudflare load-balances traffic between the new healthy container and the old "zombie" process. 50% of incoming requests will randomly return a 502 Bad Gateway.
Fix:

Find the zombie: sudo ps aux | grep cloudflared

Kill the duplicate PIDs: sudo kill -9 <PID>

Prevention: Always add init: true to the cloudflared service in docker-compose.yml. This forces Docker to use a proper init system (Tini) as PID 1, which reliably reaps and kills child processes.

[!CAUTION]
OOM (Out of Memory) Hangs
If the VM lacks sufficient memory (e.g., using an e2-micro with 1GB RAM for a heavy Node.js app), the application may freeze without the container crashing. The status will show Up X minutes, but the application's event loop is blocked.

Symptom: cloudflared cannot proxy requests, Cloudflare times out after 15 seconds, and returns a 502. Running the diagnostic internal curl command will hang indefinitely.
Fix: Increase the VM machine type (e.g., to e2-medium 4GB) or configure swap space.

[!NOTE]
Protocol Mismatch (HTTP vs HTTPS)
While end-to-end HTTPS is the recommended best practice, this guide uses plain HTTP internally for simplicity. If a protocol mismatch occurs, connectivity will fail.

If the internal service expects HTTPS, but cloudflared sends HTTP, the connection will be dropped immediately.

If cloudflared is configured to send HTTPS, it will fail if the internal service presents an untrusted/self-signed certificate (unless configured to skip TLS verification).

Ensure the protocol configured in the Cloudflare Zero Trust Dashboard perfectly matches what the internal container expects.

Configuring Firebase AI Logic for Android to Use Gemini Models

Héctor Romero — Wed, 10 Jun 2026 20:13:47 +0000

What device do we use almost all the time? Our mobile phone, almost certainly. If we wanted to develop mobile apps, we would have wondered how to integrate Artificial Intelligence (AI) into our projects in some way, given its increasing boom.

Some advances have been made with Gemini Nano and Gemma 4 as on-device AI. However, Gemma 4 is a recent release that doesn’t yet have enough maturity in most of cases, due to hardware limitations and model’s own capabilities. These are cases where using models like Gemini shines, which offer higher quality responses, can generate multimodal content and can extend their functions through third-party integrations.

I want to address this topic in two different posts: this first one will explain how you can configure Firebase AI Logic with an Android app; and I will later publish another post with two demos that I showcased at Build With AI 2026, hosted by the GDG Cali chapter.

What is Firebase AI Logic?

Firebase presents Firebase AI Logic as a service focused on offering Gemini API calls to client-side applications, including Android, iOs, web and even experiences developed with Unity.

Firebase is a platform that accelerates the app development for developers that don’t want to build a backend server to build their MVPs or proof of concept, offering a wide range of services like Realtime database, Cloud Storage, Authentication and so on.

With regard to pricing, Firebase AI Logic can be used both in Spark plan and Blaze plan, distinguished by the access of more advanced models and charges for consumption in this last one. If you want to start to experiment with AI in your apps, the Spark plan offers a free tier for the majority of Firebase services.

How I can start to use Firebase AI Logic?

The first step is to access the Firebase console and create a new project using a personal Google account — this is the recommended approach. During the setup, Firebase will ask whether you want to enable AI assistance within the platform and whether you want to activate Google Analytics — both options are optional and do not affect how AI Logic works.

After pressing the “Continue” button, you will land on the Firebase home screen, where a side navigation menu appears on the bottom-left. From here, you can access and manage all platform services. To navigate to AI Logic, find the “AI Services” section, expand it, and select the “AI Logic” option.

You will see a welcome screen for the Firebase AI Logic section along with a “Get started” button. Once you press it, a modal will appear asking you to select the Gemini API provider for your project: Gemini Developer API or Vertex AI Gemini API.

Gemini API providers

Gemini Developer API: available starting from the Spark plan, it offers a generous quota at no cost and lets you experiment without needing to link a billing account — perfect for getting started with this service. Note that image generation models are not available as of this post’s publication date.
Vertex AI Gemini API: designed for production and enterprise-scale use, it gives you access to the most advanced Gemini models (including image, video and audio generation). It requires the Blaze plan to be activated, and you will be charged for the input and output tokens you use.

Note: For more information on pricing and which Gemini models are available on each plan, check out this link.

Depending on the provider that you choose, you will need to follow a series of steps to activate it. Follow the instructions on the platform according to your case.

Firebase AI Logic SDK configuration in Android

Once you reach the “Add Firebase SDK” option after configuring the selected provider, we need to navigate to our Android Studio project. Firebase displays a form with two fields — the android package name (required) and the app nickname (optional). The package name corresponds to applicationId value in the app-level build.gradle.kts file. You can verify this by opening that file — you will find that namespace and applicationId share the same value, which will be the identifier that you need to enter.

When you press “Register app”, you will be given the option to download google-services.json file, which must be moved to the root directory of the app module in your project. To place it correctly in Android Studio, switch the file explorer view to Project (instead of Android), navigate to the /app folder, and place the file there, at the same level as the module’s build.gradle.kts.

After that, we need to go to gradle/libs.versions.toml file and add the following lines of code related to the Firebase and Google Services dependencies, as shown below:

// libs.versions.toml

[versions]
google-services = “4.4.4”
firebase-bom = "34.11.0"

[libraries]
firebase-bom = { module = "com.google.firebase:firebase-bom", version.ref = "firebase-bom" }
firebase-ai = { module = "com.google.firebase:firebase-ai" }

[plugins]
google-services = { id = "com.google.gms.google-services", version.ref = "google-services" }

We will then open the project-level build.gradle.kts file and add the line alias(libs.plugins.google.services) apply false inside the plugins block.

In the app/build.gradle.kts file, we will add alias(libs.plugins.google.services) to its plugins block, and add the following Firebase libraries inside the dependencies block:

// Google Services - Firebase AI Logic

implementation(platform(libs.firebase.bom))
implementation(libs.firebase.ai)

By using platform(libs.firebase.bom), we don’t need to worry about version compatibility across all Firebase packages, since this implementation handles compatibility for all of them automatically.

As we approach the final step, we need to go to the configuration tab of our Firebase AI Logic project and enable the required Gemini Developer APIs if we are using the Spark plan, or the Vertex AI Gemini API if we are using the Blaze plan. In both cases, I recommend enabling the AI monitoring option, as it will allow you to see — directly within Firebase — how many tokens each request consumes, what content it contains, and other relevant data.

After all this groundwork, we are finally ready to start integrating generative AI into our Android apps. Since this configuration process turned out to be quite extensive, I decided to split my original post into two parts — this being the first one, covering the full step-by-step exploration of the tool, and a follow-up post where I will showcase demos using both provider APIs, sending images and text to the Gemini model and even getting it to generate images based on the prompt we provide. In the meantime, you can check out my code from the Build With AI 2026 workshop that I will explain coming soon here.

If you want to learn more about this topic, check out the official Firebase AI Logic guide . I will be back with more Android and AI content :)

The perfect background music for Vibecoding...

Michael Ramich — Mon, 08 Jun 2026 18:01:28 +0000

While vibecoding, you sometimes need some background music. But music can also be a massive distraction. A summary of my journey in finding the perfect background tune.

I started with rap, then techno, then the 90s and 2000s… but they all failed for one reason: They are designed to be listened to actively. They steal your focus.

So I switched to Lo-Fi. It was calm, but it stimulates Alpha waves, which eventually made me sleepy.

So, what is left?

Looking for the perfect tune for Vibecoding, I found an absolute gem:

Stronghold and Anno music.
Finding these soundtracks was like finding the holy grail.

Part of it is pure nostalgia.

But there is a real psychological reason behind it:
Music from 'endless' strategy games is literally engineered to let your brain think freely while keeping you awake.
No vocals. Keeps the language regions of your brain completely free to focus on the code.

It's the perfect balance. It features dynamic elements to keep you alert, yet it is monotonous enough to fade into the background.
It's literally designed for decision-making. It pushes you to be able to complete complex strategy choices without draining your drive.

Combine this with Vibecoding and nostalgia. And you have the perfect workflow drug.

Stronghold Music:

Anno:

Happy (vibe-)coding!

Morning Security Report with Antigravity Agent

Alexander Tyutin — Mon, 01 Jun 2026 04:49:31 +0000

The latest Antigravity updates announced at Google Next brought a lot of interesting features. I am still discovering the details, but one feature really caught my attention.

Now we have separated Antigravity Agent and Antigravity IDE into two different applications. Among the new features, I found scheduled tasks and I already use them every day. What can I highlight here?

You can listen a podcast generated based on this publication (thanks NotebookLM):

Money saving

I love to maximize my ROI (How I maximized my Google Antigravity ROI). I have the cheapest paid plan. It gives me a 5-hour limit window. The limit spending starts with the first use. So, if I am not using any model, the limit is still 5 hours.

From the FinOps perspective, it is a good idea to organize usage so that one or two 5-hour windows run while I am not at my laptop. Then, a new 5-hour window should start when I begin my work in the morning. Antigravity Agent scheduled tasks are a great way to maximize ROI while minimizing effort.

Cognitive Load Reduction

I am a security guy. But I hate security when I am acting as a developer for my own product. So I try to automate not only security routines but the whole security review process.

I already have an Antigravity Workflow to automate the start of a security review (AI-powered repository security check with Antigravity Workflow) and a Quality Gate which helps me to perform a security review of a new MR (How to build a custom AI quality gate on Cloud Run from zero to production). But I still need to do some manual work and think a lot after getting the outputs of these tools.

Kaizen

The security workflow I mentioned above is a good approach. But in case of massive changes, it may require a lot of time to fix findings. That is why the Quality Gate was born. However, all of these tools run when I am working on the product. So I spend my time on security while acting as a developer.

With scheduled tasks, I can perform a deep security review of my repo while I am not working. And it is a real hit! I can not only ask the agent to review the code with its eyes, but it can also run scripts and make calls to external services during the check.

Even more, it can generate a task for me with described fixes. Or, even better, it can generate the code and provide me with the fixes right after the security review - but before I start my working day!

Here is how it looks in practice. I can find the scheduled tasks right in the new Antigravity Agent sidebar:

I configure the agent to act as a scheduled security reviewer. It checks the architecture and code of my jira-auto repository. It finds critical vulnerabilities like SSRF and insecure network configurations, and creates a clear summary:

The agent goes further and generates a detailed "Security Review Digest" artifact with a Threat Severity Matrix. This makes it very easy to understand the impact and prioritize the work:

And the best part? I can ask the agent to implement the fixes for these issues. It resolves the blockers, updates the code, and gives me a finalized security documentation showing that the repository is now 100% green:

I see how this feature helps me to move from just a local MVP to a really interesting setup for automating my developer lifecycle.

Bonus

The prompt used:

You are a scheduled security reviewer of the repository.
Your task is to perform thorough code review from security perspective.
You want to find a cause in the code to block the next MR.
You check not only code itself, but also:
- Architecture.
- Data processing.
- Users intercations.
You also search for similar code in Github to find:
- Issues around security and whether they are similar to the code checked.
- CVE related to the code checked.
- CWE related to the code checked.
- Best practices related to the code checked.
- Recommendations related to the code checked.
In case you can't find the cause to block the checked code you always can find an improvement recommendation.
Generate a digest with findings and recommendations related.