DEV Community

Motion, Stylus, Trackpads And Foldables In The Core

Shai Almog — Sun, 12 Jul 2026 14:23:42 +0000

For a long time, mobile meant a touch screen and a few platform-specific escape hatches. That is no longer enough. A Codename One app can run on phones, tablets, desktops, watches, TVs, browsers, foldables, touch laptops, external displays, cars, and devices with pens, mice, and trackpads.

What is Codename One? Codename One is an open-source framework for building native iOS, Android, desktop, and web apps from a single Java or Kotlin codebase. Learn more at codenameone.com.

PR #5310 and PR #5309 make that hardware visible through core APIs instead of cn1libs and platform branches.

Motion Sensors And Gestures

The new com.codename1.sensors package exposes accelerometer, gyroscope and magnetometer readings. It also derives gravity, linear acceleration and orientation in the core when the platform does not provide them directly.

MotionSensorManager sensors = MotionSensorManager.getInstance();
MotionSensor accel = sensors.getSensor(MotionSensorManager.TYPE_ACCELEROMETER);

if (accel != null) {
    MotionSensorListener listener = new MotionSensorListener() {
        public void motionReceived(MotionEvent evt) {
            label.setText(evt.getX() + ", " + evt.getY() + ", " + evt.getZ());
            label.getParent().revalidate();
        }
    };
    accel.addListener(listener);
}

The manager itself is always available. Individual sensors return null when the hardware is unsupported, so the app can keep one code path with a small capability check.

Gestures are built on top of the sensor stream in the core:

MotionSensorManager.getInstance().addGestureListener(
        GestureEvent.TYPE_SHAKE,
        new GestureListener() {
            public void gestureDetected(GestureEvent evt) {
                Dialog.show("Shaken", "You shook the device", "OK", null);
            }
        });

The recognized set is practical rather than exotic: shake, flip face down, flip face up, tilt left, tilt right, tilt forward, tilt backward, pick up and free fall. Because recognition lives in GestureEngine, every port that exposes an accelerometer gets the same behavior.

Sampling is reference counted. The hardware powers on while listeners exist and powers down when they are removed. On iOS you still need ios.NSMotionUsageDescription with a user-facing reason for motion access.

Rich Pointer Detail

Classic pointer callbacks tell you where a press happened. Modern input asks more questions: was it a mouse, a finger, a stylus, or an eraser? Which button? What pressure? Was the pen tilted? Was the pointer hovering?

PointerEvent is the snapshot attached to pointer action events:

myComponent.addPointerPressedListener(e -> {
    PointerEvent pe = e.getPointerEvent();
    if (pe.isSecondaryButton()) {
        showContextMenu(pe.getX(), pe.getY());
    }
    drawPreview(pe.getX(), pe.getY(), pe.getPressure());
});

You can also poll the current dispatch state through CN:

int button = CN.getPointerButton();
float pressure = CN.getPointerPressure();
boolean pen = CN.isStylusPointer();
PointerEvent current = CN.getCurrentPointerEvent();

On plain touch screens these values have safe defaults: primary button, pressure 1.0, touch or unknown pointer type. Existing apps keep working.

Wheel, Trackpad And Context Menus

WheelEvent is now the cross-platform scroll-gesture event. It handles mouse wheels, precision trackpads, horizontal scrolling, iOS/iPadOS pointer devices and the Apple Watch Digital Crown through the same path.

canvas.addMouseWheelListener(e -> {
    WheelEvent w = (WheelEvent)e;
    if (w.isControlDown()) {
        zoom(w.getDeltaY());
        w.consume();
    }
});

Consuming the event suppresses the default scroll. That is the difference between "wheel scrolls the container" and "control plus wheel zooms a design surface."

For context menus, use the higher-level listener:

label.addContextMenuListener(e -> {
    e.consume();
    showMyContextMenu(e.getX(), e.getY());
});

It fires for right click, stylus barrel button and long press, which is exactly the kind of cross-platform behavior app code should not have to rediscover.

Trackpad magnify and rotate gestures route to component methods:

Container photo = new Container() {
    protected boolean pinch(float scale) {
        zoom(scale);
        return true;
    }

    protected boolean rotation(float radians) {
        rotate(radians);
        return true;
    }
};

Stylus And Foldables

Stylus support exposes pressure, tilt, contact size and eraser type. A drawing surface can listen only to stylus events:

drawingArea.addStylusListener(e -> {
    PointerEvent pe = e.getPointerEvent();
    float width = 1f + pe.getPressure() * 9f;
    if (pe.isEraser()) {
        erase(pe.getX(), pe.getY());
    } else {
        drawPoint(pe.getX(), pe.getY(), width);
    }
});

Foldables use DevicePosture:

DevicePosture posture = CN.getDevicePosture();
if (posture.isFoldable() && posture.isTableTop()) {
    layoutForTableTop(posture.getFoldBounds(null));
}

CN.addPostureListener(e -> relayoutForPosture(CN.getDevicePosture()));

On Android, foldable support is opt-in with android.foldableSupport=true, so apps that do not need the AndroidX window library do not carry it. The simulator can generate posture changes for testing.

Wrapping Up

Input used to mean key codes, pointer coordinates, and maybe a scroll wheel. That model is too small now. A modern app has to reason about pointer type, pressure, hover, buttons, tilt, posture, trackpads, sensor sampling, and gestures that may or may not exist on the current device.

The new APIs do not make that complexity disappear. They put it behind capability checks and default-safe events, so the same component can handle a finger on a phone, a stylus on a tablet, a mouse on desktop, and a foldable hinge without turning every screen into platform-specific code.

26 Repos in 29 Days With an AI Pipeline: What Actually Broke

Lucian (LKB) — Sun, 12 Jul 2026 14:20:35 +0000

This was originally published on the LK Forge blog, where the commit chart is interactive and you can play the AI games it talks about.

Between June 5 and July 3, 2026, I took an empty domain to 26 repositories, 1,549 commits, and 335 live pages — one developer, working with Claude Code. The interesting part isn't the volume. It's which failure modes showed up, because none of them were the ones the AI-coding debate argues about.

The numbers


Repositories	26
Days	29
Commits	1,549
Pages shipped	335

Commit cadence: ~53/day average, peak 122 on June 20, exactly one zero-commit day in the sprint. The two heaviest days at the tail (114 each) were a site-wide URL-structure migration — which is itself one of the failure stories below.

The setup

Deliberately boring: one developer, Claude Code in the terminal, git for everything, static-first architecture. Games and tools are self-contained repos of vanilla HTML/CSS/JS; the hub site is Astro. Everything deploys to Cloudflare Workers with static assets at the edge — no backend, no database, nothing to babysit at 3am.

Every session ran the same loop: describe the goal, let the model plan and build, review the diff, make it verify its own work against the live site, commit. That verification step is what earns its keep — every failure below was caught by a check, not by luck.

What the pipeline was genuinely good at

Working classical-AI engines, first try or close. The 2048 solver is real expectimax search with a corner-snake heuristic and adaptive depth. Before publishing any performance number, I ran the exact production code through 250 headless self-play games: it reaches the 2048 tile in 69.6% of games at ~0.5ms per move. The tic-tac-toe opponent is minimax with alpha-beta; the pathfinding in Color Lines is BFS. Textbook algorithms, correctly implemented, shipped in days. That part of the hype is real.

Volume with consistency. 335 pages sharing one brand system, one URL convention, one schema pattern. Once a convention was written into a project memory file, the model applied it across dozens of pages without drift. Those memory files turned out to be the highest-leverage artifact in the whole pipeline.

Audits at a depth a human won't sustain. Full link-graph crawls, redirect-chain verification across hundreds of URLs, per-page canonical checks against live HTTP. The model does the 400-URL tedium without getting bored — which matters, because tedium is where site-wide bugs hide.

What actually broke

Not one failure was a syntax error, a broken build, or code that didn't run. Every real problem was structural — invisible in any single diff, only visible when you look at the whole system.

1. The pipeline competed with itself

Asked for a word-tools hub, the pipeline built one — at /word-tools/, while the existing tools lived under /tools/. Two pages on the same domain targeting the same queries: textbook SEO cannibalization, self-inflicted. Search Console showed both URLs impressing for the same terms before I consolidated with a 301. Each page was locally correct; nobody was watching the query-level picture.

Lesson: the model optimizes the page you asked for, not the site you already have.

2. Twenty-six repos, two URL conventions, weeks of cleanup

Some tools were built as flat files (page.html), others as directories (page/index.html). On Cloudflare's asset serving those get opposite trailing-slash behavior — so the site accumulated canonical mismatches, two-hop redirect chains, and Search Console redirect errors. The fix consumed the two biggest commit days of the sprint and produced a written URL convention plus a pre-deploy crawl checker that now gates every release.

Lesson: conventions the model must follow have to be written before repo #2, not after repo #20.

3. Source and production drifted apart silently

Game repos are mirrored into the hub site for deployment. Over weeks, SEO improvements were applied to the production mirror and never back-ported to source. The trap armed itself: the obvious "sync" — copy source over mirror — would have silently destroyed live metadata. It was caught only because a diff-before-copy check is now mandatory.

Lesson: any two copies of the same file will diverge, and the AI won't notice unless a check forces the comparison.

4. The verification tools lied too

The first link-graph audit reported a wave of orphaned pages. False alarm: it compared absolute URLs against unresolved relative hrefs. A later canonical audit reported 123 mismatches — also false, because the checker assumed file paths equal serving paths, and the CDN serves clean URLs. In both cases the audit tooling — also AI-written — had the bug, and acting on its output would have "fixed" a healthy site into a broken one. Both caught the same way: probe the live site before believing static analysis.

Lesson: verify the verifier. An AI-written check inherits every blind spot of the AI that wrote it.

The economics: 93% of the cost was re-reading, not writing

The sprint produced 44 working sessions and 826MB of transcripts. When I audited the token bill, the headline wasn't generation cost: roughly 93% of token consumption was cached context being re-read, turn after turn, inside marathon sessions that should have been split up.

The mechanics are mundane. A long session accumulates giant context; every subsequent turn re-reads it; a session that drifts across three unrelated tasks pays the full history of tasks one and two as a tax on task three. The model never complains, so nothing forces you to notice.

The fix cost nothing: clear context between tasks, keep durable knowledge in small memory files, treat "one session = one task" as the default. If you run an AI coding workflow and have never audited where the tokens actually go, that single check is probably worth more than any prompt engineering.

What it earned (honest version)

Over the last 28 days the site drew 207 clicks from 7,320 impressions across 257 pages with search data. For a domain about five weeks old, that's a normal, healthy trajectory — and nobody's growth-hack screenshot.

The detail worth reporting: the single biggest click-earner after the homepage is the 2048 game with the visible AI solver — the page where the most genuine engineering lives. Search demand followed the depth, not the page count. 300 thin pages didn't beat one page with something real on it.

The rules that survived

Every one exists because its absence caused a real incident above. That's the only rule-making process that works.

Benchmark before you publish a number. If it isn't measured, it doesn't ship.
Diff before you copy. No exceptions for "they should be identical."
Probe live before believing static analysis. An audit result is a hypothesis until production confirms it over HTTP.
Write conventions down before scaling them — in a memory file the model loads every session, not in your head.
One session, one task. Context is the real cost center.
Check the whole site, not the diff. Cannibalization, drift, and convention splits are invisible at diff level.

The live version, the interactive commit chart, and the AI games are at lkforge.com. The 2048 solver writeup with the full benchmark is here.

We Built a Live Face Swap Preview in the Browser

mix — Sun, 12 Jul 2026 14:17:58 +0000

We built Vivify's Live Face Swap to transform a webcam feed while the session is running.

Unlike an upload-and-wait face swap, it responds to movement and expression in the browser. The most interesting work was keeping access short-lived, metering an open-ended session, and deciding what the first release should not do.

What you can try in the browser

Upload a reference image and press Start. The transformed stream appears beside the camera feed, so movement and expression are visible without rendering a clip first.

Two design challenges

Session access: the server issues a short-lived credential when the preview starts, keeping the reusable provider key off the client.
Open-ended usage: unlike a normal generation job, a live session has no fixed duration. We meter active time with heartbeats, settle the final partial segment when it ends, and show usage while it runs.

Where the first release stops

The browser version is preview-only: it does not record, export, or save the transformed stream. We also ask users to use only their own face or images they have permission to use.

Try live face swap browser preview on Vivify. What would you test first: identity consistency, latency, expression preservation, or recovery after occlusion?

Closed World Innovation: Stop Telling People to "Think Outside the Box." There Is No Box.

Tawanda Nyahuye — Sun, 12 Jul 2026 14:14:21 +0000

"Think outside the box!"

Great advice. Incredibly helpful. One small problem: nobody knows where the box is.

What even is creativity, anyway?

Before we get to boxes and closed worlds and all that fun stuff, let's settle on what creativity actually means, because "be creative" is about as actionable as "be taller."

Creativity is when two things are both high at the same time: originality and usefulness. That's it. Something no one's ever seen before and something that actually works. Just weird? Not creative. Just useful? Also, not creative, that's just engineering. Both? That's the good stuff.

There's also simplicity in the mix, but let's not get greedy.

Why "think outside the box" is terrible advice

Here's what actually happens when you tell someone to think outside the box.

They imagine a box. Then they try to think around it. And because the box they imagined is shaped by the exact same problem they're trying to solve, they end up either with solutions so bizarre they'd never survive contact with reality, or they circle all the way back to the traditional solution they started with.

You've just run a very tiring mental exercise to arrive at the answer you already had. Congratulations.

The phrase also has another problem: in the real world, there are no boxes. No one drew a boundary around your problem and labeled it "the box." The "box" is just a metaphor that your brain takes too literally and then gets confused by.

The correct term, the one that actually helps, is the Closed World.

So what's the Closed World?

The Closed World was discovered by a researcher named Roni Horowitz, and the idea is almost annoyingly counterintuitive:

Ideas are more creative when they are confined to what's already around you.

Not outside. Not somewhere exotic. Right there. The resources, people, components, and constraints you already have are your closed world. And here's the punchline: constraints don't kill creativity. They enhance it.

Think about soldiers frying eggs on a shovel over a campfire because there's no pan. Or a forklift being used as an improvised cherry picker because there's no ladder tall enough. Nobody went outside their world to solve those problems. They looked at what they already had and asked: what else can this do?

That's the closed world doing its thing.

Why constraints are actually your friends

You'd think unlimited freedom would produce unlimited creativity. That sounds logical. It is also completely wrong.

When you have too many options, your brain does the creative equivalent of standing in front of a massive restaurant menu for twenty minutes and ordering a burger. You default to the familiar because the familiar is safe, and you're overwhelmed.

Constraints force your brain to actually work. When you can't reach outside the problem, you start looking at the problem differently. You start noticing things about what you have that you'd ignored before. Sometimes the solution was sitting right there the whole time, like the answer to a riddle you'd been overthinking.

The thing traditional thinking gets wrong about problems

Traditional thinking says: problems are bad, solutions are good. Get rid of the problem as fast as possible and replace it with a solution.

This sounds sensible. It is also why so many solutions are completely forgettable.

If you sprint away from a problem, you never actually understand it. And if you don't understand it, you can't use it. Because here's the thing: in many cases, the problem itself is part of the creative solution.

The problem contains information. It contains context. It contains constraints. And those constraints, if you work within them instead of around them, are exactly what will lead you to something original and useful, you know, the two things that make something creative.

Apollo 13, the ultimate closed world story

If you want to see closed world thinking in action at its most dramatic, look up the Apollo 13 CO2 filter problem. The astronauts had square filter cartridges. The ship needed round ones. People were going to die.

The engineers at NASA didn't order new parts. They couldn't. They couldn't go outside the closed world; they were literally 200,000 miles from the nearest hardware store.

So they sat down with exactly what was on that spacecraft and figured out how to fit a square peg in a round hole. And they did.

That's not thinking outside the box. That's thinking inside the only world available, and doing it brilliantly.

So what do you actually do with this?

Next time you're stuck on a problem, instead of trying to escape it, do this:

Draw your closed world. What people, tools, components, and resources are already part of this situation? What's right in front of you that you haven't thought to repurpose? What does the problem itself tell you about the solution?

Then stay there. Don't go looking for something exotic. The opportunity is usually right under your nose; you've just been too busy looking for a box to climb out of.

Stop thinking outside the box. Start thinking inside the closed world. The answers you need are probably already in the room.

Fervor: Turn Your Passion into a Personalized Learning Roadmap with Google Gemini AI

Abubakar umar — Sun, 12 Jul 2026 14:08:03 +0000

This is a submission for Weekend Challenge: Passion Edition

Fervor – Turn Your Passion into a Personalized Learning Roadmap with AI

What I Built

Fervor is an AI-powered web application that helps people transform their passion into a clear, personalized learning roadmap.

Many people know what they want to learn but don't know where to start. Whether it's web development, graphic design, data science, or any other skill, the biggest challenge is creating a structured learning path.

Fervor solves this problem by asking users about:

Their passion
Their learning goal
Current experience level
Motivation
Weekly study time

Using Google Gemini AI, Fervor generates a personalized roadmap that includes:

A clear learning goal
Estimated learning duration
Three progressive learning stages
Actionable tasks for each stage
Daily motivational advice
Progress tracking
Local storage so users can continue where they left off

The goal was to create an application that feels like having a personal AI learning coach.

Demo

Live Demo

fervor-ai.vercel.app

GitHub Repository

sadikumar6413 / Fervor

Fervor is an AI-powered web application that transforms your passion into a personalized learning roadmap using Google Gemini AI.

The complete source code is available on GitHub:

sadikumar6413 / Fervor

Fervor is an AI-powered web application that transforms your passion into a personalized learning roadmap using Google Gemini AI.

How I Built It

Fervor was built using:

HTML5
CSS3
Vanilla JavaScript
Google Gemini API
Local Storage
Git & GitHub
Vercel

One of the biggest challenges was integrating the Google Gemini API.

During development I encountered several issues, including:

Incorrect API configuration
JavaScript bugs preventing roadmap generation
API request errors
HTTP 429 rate limit responses
JSON parsing challenges when processing AI responses

Debugging these problems taught me a lot about working with REST APIs, asynchronous JavaScript, error handling, and building resilient user experiences.

Once the AI integration was working, I focused on creating a clean interface that keeps users focused on their learning journey instead of overwhelming them with information.

Every generated roadmap is personalized based on the user's goals, making each experience unique.

✅ Best Use of Google AI

Google Gemini powers the heart of Fervor.

It analyzes the user's interests, experience level, motivation, and available study time to generate a structured, personalized learning roadmap instead of returning generic advice.

The AI creates:

Personalized learning paths
Progressive milestones
Actionable learning tasks
Estimated timelines
Motivational coaching

Google AI transformed what would have been a static checklist into a dynamic and personalized learning experience.

What I Learned

This project reminded me that software development is much more than writing code.

Building Fervor challenged me to think about user experience, AI integration, debugging, and resilience.

Every bug solved taught me something new, and every successful AI response felt like another milestone in my journey as a developer.

As a Computer Science student, this project pushed me beyond my comfort zone and gave me hands-on experience building and deploying a real AI-powered application.

I'm excited to continue improving Fervor by adding secure backend integration, user accounts, cloud synchronization, and more intelligent AI coaching.

Thank you for checking out my project!

weekendchallenge

One Header, Full Admin: Attackers Exploit Critical Auth Bypass in Gitea Docker Images

Etairos.ai — Sun, 12 Jul 2026 14:06:16 +0000

TL;DR

what: CVE-2026-20896, a critical authentication bypass in the default configuration of official Gitea Docker images through 1.26.2, is under active exploitation via spoofed X-WEBAUTH-USER reverse-proxy headers.
impact: Attackers can impersonate any user, including administrators, with no password or token, giving them full control of source code, CI secrets, and everything downstream of the compromised Git server.
fix: Upgrade to Gitea 1.26.4 (1.26.3 fixed the flaw but introduced a regression) and lock REVERSE_PROXY_TRUSTED_PROXIES to explicit trusted IPs instead of a wildcard.
who: Anyone running the official Gitea Docker image, especially the roughly 6,200 instances reachable from the public internet, and any org whose CI/CD pipeline trusts that Gitea as a source of truth.

No password. No token. One header. That is the entire exploitation story for CVE-2026-20896, a critical authentication bypass in the official Gitea Docker images that attackers began exploiting in the wild just 13 days after the advisory went public. If you run Gitea from the official container image at version 1.26.2 or earlier, an unauthenticated attacker who can reach your instance may be able to log in as any user on the system, including your administrators, by adding a single HTTP header to their request.

The exposure is not theoretical. Roughly 6,200 Gitea instances are reachable on the public internet right now. Not all of them are confirmed vulnerable, but scanning is already underway: Sysdig security researcher Michael Clark observed a VPN-exit scanner probing specifically for this flaw, and Singapore's Cybersecurity Agency has issued its own alert urging immediate patching.

The flaw: trusting a header anyone can send

Gitea, like many self-hosted services, supports reverse-proxy authentication. In that model, an upstream proxy such as nginx or an SSO gateway authenticates the user, then forwards the request to Gitea with an identity header, X-WEBAUTH-USER, telling Gitea who the user is. Gitea trusts that header and creates a session for the named account. The whole scheme depends on one assumption: only the trusted proxy can set that header.

In the affected Docker images, the default configuration breaks that assumption. Deployments with reverse-proxy authentication headers enabled will accept X-WEBAUTH-USER from sources that were never supposed to be trusted. An attacker sends a request with X-WEBAUTH-USER set to an admin username, and Gitea obligingly h ands them that admin's session. No credential check, no second factor, no token. The header is the authentication.

⚠️ Full admin impersonation with zero credentials — Because the bypass lets an attacker specify any username, the ceiling is total compromise. Impersonate an administrator and you own the repositories, the webhooks, the deploy keys, the CI/CD secrets, and the ability to push malicious commits into everything downstream that trusts this Git server. Treat any exposed, unpatched instance as already breached until logs prove otherwise.

The exploitation timeline

This is a genuine active-exploitation story, not a proof-of-concept warning. The advisory for CVE-2026-20896 was published, and first in-the-wild exploitation followed 13 days later, well inside the window most organizations need just to notice a new CVE, let alone deploy a patched container across their fleet. The takeaway for defenders is blunt: the patch gap here is measured in days, and the attacker cost is a single crafted request.

Patch carefully: 1.26.3 is not enough

Gitea shipped a fix in 1.26.3, but that release introduced a regression, and 1.26.4 is the version that resolves both the vulnerability and the regression. Do not stop at 1.26.3. Pull the official image at 1.26.4 or later, redeploy, and confirm the running container reports the patched version rather than assuming your orchestration picked up the new tag.

Upgrade the official Gitea Docker image to 1.26.4 or later; do not settle for 1.26.3, which carries a known regression.
Set REVERSE_PROXY_TRUSTED_PROXIES to the explicit IP addresses of your real proxies. Never use a wildcard, which trusts every source.
If you do not use reverse-proxy authentication, disable it entirely so X-WEBAUTH-USER is ignored.
Restrict public exposure. A self-hosted Git server rarely needs to answer requests from the entire internet; put it behind VPN or IP allowlisting.

Assume compromise and hunt for it

Patching closes the door, but if your instance was exposed and unpatched during the exploitation window, you need to determine whether someone already walked through it. Review access logs for requests carrying an X-WEBAUTH-USER header from IPs that are not your legitimate proxy. Look for admin logins with no corresponding credential event, new or altered SSH and deploy keys, unexpected webhook changes, and repository pushes or org membership changes you cannot account for. Because the bypass leaves a valid-looking session, the header origin in your proxy and application logs is often the clearest tell.

The bigger lesson: header trust is a systemic pattern — X-WEBAUTH-USER, X-Forwarded-For, X-Remote-User and their cousins show up across countless self-hosted apps, and every one of them is only as safe as the network boundary that is supposed to strip client-supplied copies. Audit every service in your stack that authenticates on a trusted header, confirm the upstream proxy strips inbound copies of that header, and never leave the trusted-proxy list set to a wildcard default.

Gitea is a supply-chain chokepoint: it holds your source, your build config, and the keys to your pipeline. An auth bypass that hands an attacker administrator access to that chokepoint is about as bad as self-hosted vulnerabilities get. With active scanning confirmed and roughly 6,200 instances exposed, the safe assumption is that unpatched, internet-facing Gitea is being found right now. Get to 1.26.4, lock down the trusted-proxy list, and pull your logs before you close the ticket.

Originally published on RedEye Threat Intelligence.

PassionProof — A Soulbound NFT for Consistent Open Source Contribution

Lymah — Sun, 12 Jul 2026 14:02:12 +0000

This is a submission for Weekend Challenge: Passion Edition

What I Built

PassionProof is a Solana program that mints a soulbound badge for a real contribution, then makes it permanently, provably non-transferable.
Digital achievements are usually transferable, sellable, or detached from the person who earned them. I wanted to explore the opposite: what if recognition for real contribution couldn't be traded? PassionProof issues a Token-2022 badge that's locked to the wallet it was minted to, carrying an on-chain "reason" field recording exactly what it's for.

My own path into this space started as a self-taught, career-shifted developer — I hold a Biochemistry degree, not a CS one, and the thing that proved to me (and eventually to others) that I belonged in this field was becoming a core contributor to statix, a Nix linter now canonical in nixpkgs. That's the milestone I recorded in the badge below: awarded_for: "Merged first PR into statix". Passion isn't just saying you love something; it's showing up consistently for work that doesn't always get seen, and I wanted a way to make that kind of record permanent instead of just a line on a resume.

Demo

The recording walks through the real, on-chain test run: creating the badge mint, minting it to a recipient, then attempting to transfer it. Captions are on the video, but the key moment is worth pulling out here directly, at the point of the transfer attempt, the program log reads:

Program log: Transfer is disabled for this mint

That's Token-2022 itself refusing the transfer at the protocol level, not a check written into my own program.

Program deployed to devnet:
HSSLcVQmCdCo8qt9UBMSAL9vbqpxYLkCLHoz74dgrBE1

Real transactions on devnet:

create_badge_mint:tx/2JcbBHtyRpFCcrsNJ4jNChMy46EKCg73wtUfY2j3Qq4ADCzRWbGLvD5DWQsDMnn7WjZHwWefpCNCrrbjst94hGtq
mint_badge:tx/3NAjTLLFPf1PxkVf1BpxmLio68o357FEcaTSBA9WBjVs1KK5xKkPieSJr4UmDYmqKrAFKW6Us3nfZNSeBezESGFi

executable on devnet:" width="800" height="400">

Token-2022 instructions executed: InitializeNonTransferableMint,
MetadataPointerInstruction::Initialize, InitializeMint2, and three
TokenMetadataInstruction::UpdateField calls writing the category,
awarded_for, and recipient/issued fields — all ending in
Program returned success:" width="800" height="357">

Code

Lymah123 / passionproof

PassionProof

A soulbound Solana badge for consistent, meaningful contribution — starting with open source. Built for the DEV Weekend Challenge: Passion Edition.

Digital achievements are usually transferable, sellable, or detached from the person who earned them. PassionProof explores the opposite idea: what if recognition for real contribution couldn't be traded? Every badge is a Token-2022 mint with Solana's NonTransferable extension, permanently locking it to the wallet that earned it — plus an on-chain reason field so the badge is a verifiable record of a specific milestone, not just a picture.

Deployed and verified on devnet: HSSLcVQmCdCo8qt9UBMSAL9vbqpxYLkCLHoz74dgrBE1

What it uses

Token-2022 NonTransferable extension — enforced at the protocol level any TransferChecked instruction against the badge fails on-chain.
Token-2022 MetadataPointer + TokenMetadata extensions — metadata lives directly on the mint account, no external metadata program required.
Custom metadata fields (category, awarded_for, recipient issued) — the "reason" a…

View on GitHub

How I Built It

PassionProof is an Anchor program built on Solana's Token-2022 program,
using two of its extensions instead of a traditional NFT metadata standard:

NonTransferable extension — enforced at the protocol level. Once a badge mint has this extension, any transfer instruction against a token account holding it is rejected by the Token-2022 program itself. This isn't a convention or a frontend restriction; it's consensus-level.
MetadataPointer + TokenMetadata extensions — metadata lives directly on the mint account. No external metadata program, no off-chain indexer dependency for the core facts.

The program exposes two instructions:

pub fn create_badge_mint(
    ctx: Context<CreateBadgeMint>,
    name: String,
    symbol: String,
    uri: String,
    category: String,
    awarded_for: String,
    recipient_name: String,
) -> Result<()>

pub fn mint_badge(ctx: Context<MintBadge>) -> Result<()>

create_badge_mint initializes the mint with both extensions, then writes custom metadata fields — category, awarded_for, recipient, and issued — directly into the mint's TLV metadata. mint_badge mints exactly one unit into the recipient's associated token account. Because the mint is NonTransferable, that token account is now permanently bound to that wallet.

One honest scope note: the awarded_for field is self-attested by whoever holds mint authority; the program records what the contribution was, but doesn't independently verify it against, say, the GitHub API. The trust model is the same as a signed certificate: the record is permanent and tamper-proof once issued, but the issuing authority is what backs the claim.
GitHub-verified minting is the natural next step.

Challenges — most of my actual weekend went into infrastructure, not logic, which felt worth being honest about:

Getting a local Anchor/Rust toolchain working in WSL hit a wall when a transitive dependency required Cargo's edition2024 feature, and the Solana CLI's bundled platform-tools compiler was too old to support it. Combined with unreliable network conditions that kept timing out large toolchain downloads, I switched to Solana Playground (a browser-based Anchor IDE) to build, deploy, and test — the right call for a tight weekend timeline.
Token-2022's metadata extension requires manually funding rent as the account grows (each metadata field write resizes the account), and I initially wrote a realloc call into my program that only the account's owning program (Token-2022, not mine) was actually allowed to perform. Solana enforces account ownership boundaries strictly.
Making sure my "transfer fails" test proved the right thing, my first few attempts failed for boring reasons (empty wallet, missing destination account) rather than the NonTransferable extension itself. It took a few iterations to isolate the actual protocol-level rejection.

What I'd build next:

GitHub-verified minting, so awarded_for becomes a verified fact instead of a self-attested string
A minimal frontend: connect wallet → "Mint PassionProof" → see the badge and its "Soulbound: Cannot Transfer" state
Support for multiple contribution categories beyond open source
A path from devnet to mainnet once the extension logic has more mileage

Prize Categories

Submitting to Best Use of Solana. PassionProof uses Solana's native Token-2022 program directly, the NonTransferable extension, the MetadataPointer extension, and the TokenMetadata interface with custom fields, with no external metadata program or Metaplex dependency.

I Open-Sourced My AI Agent Framework: Agents With Character, Rules, and the Ability to Build Their Own Tools

lawcontinue — Sun, 12 Jul 2026 13:50:11 +0000

I'm a lawyer. I write contracts, not Python — except I also write Python, because the legal mindset turns out to be surprisingly useful for building AI agents that don't run wild.

This is about OpenSymphony, an agent framework I built and open-sourced under MIT. It's on PyPI (pip install opensymphony), has 395 passing tests, and runs on a Mac mini.

The thesis is simple. Most agent frameworks solve orchestration — how to chain LLM calls together. Almost none solve the harder problem: who is the agent, what rules does it follow, and who stops it when it's wrong.

The Problem

You've used LangChain agents. They're good at calling tools in sequence. They're bad at:

Consistency. The agent that was helpful yesterday is a different agent today. Prompt drift is real.
Accountability. When an agent makes a decision, there's no record of why. No precedent. No review.
Safety. You can add a system prompt that says "be careful," but nothing structurally prevents risky actions.
Growth. Agents don't learn. They make the same mistakes repeatedly.

OpenSymphony addresses these with three architectural pillars: Soul, Governance, and Self-evolution.

Pillar 1: Soul — Persistent Agent Identity

An agent's personality isn't a prompt. It's a YAML file that compiles into behavioral constraints.

# souls/my_agent.yaml
id: my_agent
name: MyAgent
archetype: Code Reviewer

thinking_framework: |
  You are a code reviewer focused on security and correctness.
  Rules:
  1. Flag any unvalidated user input
  2. Check for race conditions in concurrent code
  3. Prefer readability over cleverness

values:
  - Security first
  - Evidence-based review
  - Constructive feedback

The thinking_framework is the operational logic. values are ranking principles when priorities conflict. You can also define veto conditions — hard stops that prevent certain actions entirely.

This isn't prompt engineering. The Soul Compiler transforms YAML into a structured behavioral framework that persists across conversations and sessions. The agent doesn't forget who it is.

There are 13 built-in Souls: themis (legal reasoning), athena (strategy), crit (adversarial review), shield (security), code (implementation), novelist, screenwriter, and others. Each has a distinct thinking framework, value hierarchy, and veto conditions.

The legal analogy: a Soul is like a professional code of conduct. A lawyer doesn't reinvent attorney-client privilege every time they take a case. It's baked into the framework. Same idea here.

Pillar 2: Governance — Structural Decision-Making

This is where the legal background matters most.

In a law firm, decisions go through layers. Associates draft, senior partners review, risk committees flag conflicts, and precedents guide future calls. OpenSymphony does the same thing:

Request → Gateway → [Intent Bridge] → [Governance] → Runtime → Kernel → Response
                                        ↑
                              Voting / Precedent / Defense

The governance layer has four mechanisms:

VotingMechanism — Multiple agents vote on decisions. Configurable majority rules and timeout. If you have three agents and two say "this action is safe," it proceeds. One dissent gets logged.

PrecedentStore — Past decisions become searchable precedents. When an agent faces a similar decision later, it retrieves relevant history. This is literally how common law works — stare decisis for AI agents.

DefenseLayer — Every action gets classified as safe, risky, or dangerous. Risky actions require additional review. Dangerous actions are blocked unless a human overrides.

HITLManager — Human-in-the-loop confirmation for high-risk operations. The agent proposes, a human disposes.

from opensymphony.kernel import SymphonyKernel

kernel = SymphonyKernel()
kernel.load_souls("souls/")

# The request passes through governance before execution
response = kernel.chat("crit", "Should we deploy this untested change to production?")

When you ask the crit agent whether to deploy untested code, the DefenseLayer flags it as risky. The VotingMechanism can poll multiple agents. The PrecedentStore surfaces similar past decisions. The HITLManager can require your sign-off.

No single agent makes irreversible decisions alone.

Pillar 3: Self-Evolution — Agents Build Their Own Tools

The Tool Workshop lets agents create, test, and deploy Python tools at runtime.

An agent encounters a task it can't solve with existing tools. It writes a new one, tests it, and adds it to the registry. No human intervention required — but governance still applies. A new tool goes through the same risk classification as any other action.

This matters because you can't predict every tool an agent will need. The alternative is either a massive hardcoded toolset (maintenance burden) or giving agents eval access (security nightmare). The Workshop is a structured middle ground: agents can extend their capabilities, but within a sandbox with resource limits and governance oversight.

Architecture: The Onion Model

Every request passes through concentric layers:

┌─────────────────────────────────────────────────┐
│  Gateway (HTTP / WebSocket / CLI)                │
│    └─ HumanAdapter — Intent Bridge (NL→struct)   │
├─────────────────────────────────────────────────┤
│  Governance                                      │
│    ├─ VotingMechanism — multi-agent decisions     │
│    ├─ PrecedentStore — reusable past decisions    │
│    ├─ DefenseLayer — risk assessment              │
│    └─ HITLManager — human-in-the-loop             │
├─────────────────────────────────────────────────┤
│  Runtime                                         │
│    ├─ AgentPool — concurrent agent management     │
│    ├─ TaskScheduler — priority queue              │
│    └─ AgentSandbox — resource limits              │
├─────────────────────────────────────────────────┤
│  Kernel                                          │
│    ├─ Soul Compiler — YAML → behavioral rules     │
│    ├─ LLM Router — cloud + local providers        │
│    ├─ Memory (L1/L2/L3) — three-tier storage      │
│    └─ Tool Workshop — agents create tools         │
└─────────────────────────────────────────────────┘

The Intent Bridge translates natural language into structured intents. Governance reviews the intent. Runtime manages execution with resource limits. The Kernel handles the actual work: Soul compilation, LLM routing, memory, and tools.

Nothing reaches the Kernel without passing through Governance first.

Three-Tier Memory

Agents need memory that works at different timescales:

Tier	Storage	Purpose
L1	In-memory	Current conversation context
L2	SQLite	Experience database with full-text search
L3	Cloud API	Long-term persistent memory

L1 is fast and ephemeral. L2 is where agents store lessons learned — things like "this API rate-limits at 100 req/min" or "this user prefers terse responses." L3 is optional cloud storage for cross-session persistence.

The PrecedentStore sits across L2 and L3. When an agent makes a decision, it's stored. When a similar situation arises, the precedent is retrieved. Over time, the system builds a case law of its own decisions.

LLM Routing — Cloud and Local

The LLM Router supports both cloud APIs and local models. You can route different agents to different models — a simple classification task might use a local 7B model, while complex reasoning goes to a cloud provider.

This matters for cost and privacy. A governance system that sends every decision to a third-party API is a governance system with a data leak. Local models keep sensitive decisions on your hardware.

Consumer hardware works. I develop and run OpenSymphony on a Mac mini with 16GB RAM. Local inference isn't fast, but it's functional.

What 395 Tests Get You

The test suite covers the governance layer, Soul compilation, memory tiers, the LLM router, and the tool workshop. Governance logic needs deterministic tests — you can't rely on LLM probability to verify that the DefenseLayer correctly blocks a dangerous action.

git clone https://github.com/lawcontinue/opensymphony.git
cd opensymphony
pip install -e ".[dev]"
pytest  # 395 passing, 6 known intent-bridge failures

Quick Start

pip install opensymphony
python -m opensymphony.gateway.http

Define a Soul in YAML, load it, and start talking to your agent. The governance layer is optional — you can start without it and add voting, defense, or HITL as your use case demands.

from opensymphony.agents.soul import Soul
from opensymphony.agents.soul_compiler import compile_soul

soul = Soul.from_yaml("souls/my_agent.yaml")
prompt = compile_soul(soul, output_mode="agent")

Why a Lawyer Built This

Legal systems have spent ~900 years solving a problem that AI agents now face: how do you give autonomous actors decision-making power while preventing abuse?

The answer in law is structural. Constitutions, precedent, voting procedures, defense counsel, appellate review. Not "please be careful" instructions in a system prompt.

OpenSymphony borrows these patterns. Souls are codes of conduct. The PrecedentStore is case law. The DefenseLayer is risk assessment. VotingMechanism is deliberative democracy. HITLManager is judicial review.

The goal isn't to make agents "ethical" through prompt engineering. It's to build structural constraints that make bad behavior difficult, auditable, and correctable.

Status and Roadmap

The framework is MIT-licensed and on GitHub. The 13 built-in Souls cover use cases from code review to creative writing. Application modules exist for novel pipelines and content production.

What's there now: Soul system, full governance layer, three-tier memory, LLM routing, tool workshop, HTTP/WebSocket/CLI gateways.

What's next: more Souls, better local model integration, and expanding the precedent retrieval system with semantic search.

If you build agent systems and have opinions about governance, I'd like to hear them. Issues and PRs are open.

Session Manager removes your public IPs. Is it enough for an audit?

Alex — Sun, 12 Jul 2026 13:49:54 +0000

Every public IP on an EC2 instance exists for one of two reasons: the instance serves the internet, or somebody needs to SSH into it. The second reason stopped being valid years ago, and it is still the most common one we see.

The problem

Instances get a public IP so an engineer can reach them over SSH. That single decision drags a chain of exposure behind it: a security group with port 22 open (often to 0.0.0.0/0 "temporarily"), key pairs shared over Slack and never rotated, an internet gateway route on subnets that never needed one, and a bastion host that is itself another public instance with another key pair.

From an audit standpoint, every one of these is a finding. From an attacker's standpoint, every public IP is scanned within minutes of being assigned. And from an operations standpoint, none of it is necessary: AWS Systems Manager Session Manager gives you a shell on any instance with zero inbound ports, zero public IPs, and zero SSH keys.

The biggest advantage deserves to be stated plainly: port 22 is not restricted, it is closed. Not narrowed to an office IP, not hidden behind a bastion: there is no listening port to protect at all, because access happens over the web. The shell opens in a browser tab from the AWS console (or from the CLI), authenticated by the IAM login the engineer already has.

We have applied this in two very different settings, and the experience splits cleanly. In startups and small companies, Session Manager is a pure win: public IPs disappear, key management disappears, and engineers open a shell on any instance on the fly from the console or CLI. In enterprises, the network part is just as easy, but a different question stops the rollout: once everyone enters the VM through the same door, how do you prove who did what inside it? That question, and what to ship to the SIEM, is where most of this article lives.

The finding

Session Manager inverts the connection model. The SSM Agent on the instance opens an outbound HTTPS connection to the Systems Manager service and waits. When you start a session, the service brokers it over that existing outbound channel. Nothing ever connects inbound to the instance, so there is nothing to expose. That inversion is what makes the browser shell possible: the operator's session rides the agent's outbound channel, which is why port 22 can stay closed on every instance in the fleet.

Three things have to be true for this to work, and they are smaller than most teams expect.

1. The minimum instance role

The instance needs an instance profile whose role allows the SSM Agent to talk to the service. The managed policy AmazonSSMManagedInstanceCore is the supported baseline. If you want the actual minimum instead of the managed policy, this is what the agent needs for sessions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ssm:UpdateInstanceInformation",
        "ssmmessages:CreateControlChannel",
        "ssmmessages:CreateDataChannel",
        "ssmmessages:OpenControlChannel",
        "ssmmessages:OpenDataChannel"
      ],
      "Resource": "*"
    }
  ]
}

Add s3:GetEncryptionConfiguration and s3:PutObject on your logging bucket, or logs:CreateLogStream and logs:PutLogEvents on your logging group, if you enable session logging (you should, see below). Add kms:GenerateDataKey and kms:Decrypt on the session KMS key if you encrypt sessions (you should as well).

Note what is not in this policy: nothing. No inbound rule, no key material, no ec2:*. The instance role is the entire server-side setup.

2. The minimum user policy

On the operator side, scope ssm:StartSession to the instances the person is allowed to reach. Tag-based scoping keeps this manageable:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "ssm:StartSession",
      "Resource": "arn:aws:ec2:*:*:instance/*",
      "Condition": {
        "StringEquals": { "ssm:resourceTag/Environment": "dev" }
      }
    },
    {
      "Effect": "Allow",
      "Action": "ssm:StartSession",
      "Resource": "arn:aws:ssm:*:*:document/SSM-SessionManagerRunShell"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ssm:TerminateSession",
        "ssm:ResumeSession"
      ],
      "Resource": "arn:aws:ssm:*:*:session/${aws:username}-*"
    }
  ]
}

The session-document statement matters: without pinning the document, a user who can start any session can bypass your logging preferences by choosing a different session document.

3. The network path (the "firewall")

The agent needs outbound HTTPS to three service endpoints: ssm, ssmmessages, and ec2messages. In a private subnet with no NAT, that means three interface VPC endpoints:

com.amazonaws.<region>.ssm
com.amazonaws.<region>.ssmmessages
com.amazonaws.<region>.ec2messages

The security group on the endpoints allows inbound 443 from the instance security groups (or the VPC CIDR). The instance security group needs outbound 443 to the endpoint security group and nothing else. No inbound rules at all. If session logs go to S3 or CloudWatch, add the s3 gateway endpoint and the logs interface endpoint; add kms if sessions are encrypted.

If the subnets already have a NAT gateway, the endpoints are optional (the agent will happily use the regional public endpoints over NAT), but the interface endpoints keep session traffic off the NAT data-processing meter and inside the VPC.

With those three pieces in place, the public IPs, the bastion, port 22, and the key pairs are all deletable.

When to use it, and when an auditor pushes back

Session Manager is the right default for interactive administrative access to EC2. It is not automatically audit-clean. If we were reviewing your account, this is what we would check.

Use it when access is interactive, occasional, and administrative: debugging, incident response, one-off inspection. Every session start is a StartSession event in CloudTrail tied to an IAM principal, which is already better evidence than an SSH login against a shared key.

Turn on session logging before you call it a control. Out of the box, Session Manager records that a session happened, not what happened inside it. Session activity logging to S3 or CloudWatch Logs (with KMS encryption on both the session and the destination) captures the full terminal transcript. Without it, an auditor will correctly note that your privileged access has no content trail.

The identity gap: everyone is ssm-user. This is the finding most teams miss, and in our experience it is the single point where enterprise rollouts stall. Session Manager authenticates the AWS principal, but on the operating system every session lands as the same local account, ssm-user, with sudo rights by default. Your OS logs, auditd trail, and file ownership all say ssm-user did it. If your access policy or your regulator expects OS-level actions to be attributable to a named individual (and most do), the default setup fails that requirement even though AWS knows exactly who started the session.

What the console identity already gives you. Before reaching for workarounds, know what is attributable out of the box. When a user starts a session from the console or CLI, CloudTrail records the StartSession event with their full principal ARN, and the session ID itself is generated with the IAM user name as its prefix. This is why AWS's own example policies can scope ssm:TerminateSession to arn:aws:ssm:*:*:session/${aws:username}-*. Since the CloudWatch log stream for the session transcript is named after the session ID, the transcript of everything typed and returned in the session is already tied to the console identity by name. What AWS does not do is carry that identity into the operating system: there is no mechanism that logs the console IAM user into the box as themselves, and no automatic provisioning of OS accounts from IAM identities. Inside the VM, attribution stops at ssm-user unless you configure Run As.

Workarounds for the OS-level gap:

Run As. Session Manager preferences can run sessions as a named OS user instead of ssm-user, taken from the SSMSessionRunAs tag on the IAM principal. Three constraints to plan around: it is Linux and macOS only, the root account is not supported, and once Run As is on there is no fallback to ssm-user. A missing tag or missing OS account means no session. From an audit perspective the no-fallback behavior is a feature: nobody can silently drop back to the shared identity.
Run As works per person even under SSO. The obvious objection in a federated setup (Entra ID or any SAML IdP in front of AWS) is that everyone shares the same role, so a tag on the role would map everyone to the same OS user. The answer is session tags: the IdP passes SSMSessionRunAs as a SAML attribute (https://aws.amazon.com/SAML/Attributes/AccessControl:SSMSessionRunAs) with a per-user value, and each person's role session carries their own OS user name. With IAM Identity Center, enable Attributes for Access Control and map the attribute to ${path:userName} so it flows from the directory automatically. Same permission set, individual OS identity per human.
The OS account still has to exist first. Session Manager verifies the target account before starting the session and refuses the connection if it is missing. It never creates users. That leaves an enterprise with exactly two options: provision matching Linux accounts on every node ahead of time (user data, Ansible, or a State Manager association syncing the user list), or domain-join the instances so the Run As target is a domain user that exists everywhere by definition. The domain-join path is the cleanest where AD is already present, and OS-level attribution then matches the corporate identity, but be precise about what it is: Session Manager checks that the domain account exists and runs the session as it. The mapping from AWS principal to domain user is tag-based trust, not a Kerberos logon, and an auditor should understand it as such. Note for Entra ID shops: Entra ID alone is not a joinable domain in the classic sense; this path needs real Active Directory in the picture (AWS Managed Microsoft AD, or hybrid AD synced through Entra Connect).
Accept correlation as the control for small teams: session transcripts carry the IAM identity in their name (see above), CloudTrail carries the principal, and OS logs carry ssm-user plus timestamps. Documenting that correlation procedure is defensible for low-change environments and startups. It is weak for regulated ones, because it degrades exactly when you need it most: concurrent sessions on the same instance.

When OS logs need to reach the SIEM

Session transcripts in S3 are evidence, but they are not detection. Ship OS-level logs to the SIEM when any of these hold:

Regulated workloads. If the instance is in scope for PCI DSS, ISO 27001 A.8.15/A.8.16, or similar, privileged session activity must be centrally collected and reviewed, not just stored. A transcript bucket nobody reads does not satisfy "monitored".
Run As is your attribution control. Then /var/log/secure and the auditd trail are where the named OS user actually appears, and they need to be tamper-evident and off-box. CloudWatch Agent to CloudWatch Logs, then a subscription filter to Kinesis Data Firehose into the SIEM, is the standard path and keeps the instance role additions minimal.
You need alerting on what happens inside sessions, not just that they occurred: sudo to root, package installs, outbound connections initiated from an interactive shell. That is auditd or Sysmon territory, and it only has value if a detection pipeline consumes it.

If none of those apply (dev accounts, no compliance scope, low blast radius), CloudTrail plus encrypted session transcripts is a proportionate control, and the SIEM integration can wait.

Impact

For a startup, the impact is immediate and unambiguous: public IPs deleted, port 22 closed everywhere, key pairs revoked, bastion terminated, and engineers reach any instance on the fly with nothing but their existing IAM login. The whole migration is an instance profile, three VPC endpoints, and one afternoon.

For an enterprise, the network win is identical, but the honest impact statement includes the second phase: Run As backed by provisioned OS or domain accounts, session transcripts encrypted and centralized, and OS logs flowing to the SIEM where compliance scope demands it. That phase is real work. It is still less work than operating a bastion fleet with rotating SSH keys, and unlike the bastion, it ends with every privileged session attributable to a named person at both the AWS layer and the OS layer.

The end state in both cases is the same: zero inbound ports for administrative access, and the answer to "why does this instance have a public IP" is only ever "it serves the internet".

Want us to look for issues like this in your account? We offer a free AWS audit: upstood.com

Day 74/100 - Cross-Datacenter Replication in ClickHouse®

Kanishga Subramani — Sun, 12 Jul 2026 13:46:41 +0000

Introduction

Modern applications increasingly operate across multiple geographical regions to improve availability, reduce latency, and ensure business continuity. Whether you're building a disaster recovery strategy, enabling multi-region analytics, or serving users closer to their location, replicating data across data centers has become a critical architectural requirement.

ClickHouse® supports cross-datacenter replication through its ReplicatedMergeTree table engine. Combined with a distributed ClickHouse cluster and a coordination service such as ClickHouse Keeper, it allows organizations to maintain synchronized copies of data across multiple data centers while continuing to deliver high-performance analytical queries.

This architecture ensures that if one data center becomes unavailable due to hardware failures, network outages, or maintenance, other replicas continue serving requests with minimal disruption.

In this article, you'll learn how cross-datacenter replication works in ClickHouse®, the components involved, how to configure a replicated cluster, monitor replication health, troubleshoot common issues, and follow best practices for reliable deployments.

Why Use Cross-Datacenter Replication?

Replicating data across multiple data centers offers several operational and business advantages.

Some of the primary benefits include:

High availability
Disaster recovery
Regional redundancy
Business continuity
Reduced query latency for geographically distributed users
Improved fault tolerance
Maintenance with minimal downtime
Increased read scalability

Cross-datacenter replication is commonly used in industries such as:

Financial services
Telecommunications
E-commerce
Healthcare
SaaS platforms
Media and streaming services

How Replication Works in ClickHouse®

A single-node ClickHouse deployment has one major limitation—if the server becomes unavailable, so does access to your data.

Replication addresses this challenge by maintaining synchronized copies of data across multiple nodes.

ClickHouse replication is powered by the ReplicatedMergeTree table engine.

Instead of copying entire tables repeatedly, ClickHouse replicates only the newly created data parts. Metadata about these parts is coordinated using ClickHouse Keeper, while each replica maintains its own local copy of the data.

This architecture minimizes network traffic while keeping replicas synchronized efficiently.

Some key benefits include:

Fault tolerance—if one replica fails, others continue serving queries.
High availability with no single point of failure.
Read scalability by distributing SELECT queries across replicas.
Zero-downtime maintenance by taking individual nodes offline without interrupting service.

Cluster Overview

For this example, consider a cluster consisting of one shard with three replicas distributed across three different nodes.

Node	IP Address	Role
Node 1	10.x.x.1	Replica
Node 2	10.x.x.2	Replica
Node 3	10.x.x.3	Replica

Each node stores a complete copy of the data.

If any single node becomes unavailable, the remaining replicas continue processing queries without data loss.

The overall architecture looks like this:

                Application
                     │
                     ▼
            Distributed Table
                     │
     ┌───────────────┼───────────────┐
     ▼               ▼               ▼
Node 1          Node 2          Node 3
Replicated      Replicated      Replicated
MergeTree       MergeTree       MergeTree
     └───────────────┼───────────────┘
                     ▼
            ClickHouse® Keeper

Core Components

Cross-datacenter replication relies on three primary components working together.

1. ReplicatedMergeTree

This is the storage engine responsible for replication.

Each replica stores its own copy of the table while automatically synchronizing newly inserted data with other replicas.

2. ClickHouse Keeper

ClickHouse Keeper is the coordination service responsible for managing replication metadata.

It tracks:

Available replicas
Newly created data parts
Replication queues
Leader election
Replica synchronization

Keeper uses the Raft consensus algorithm to ensure fault-tolerant coordination.

3. Distributed Table

Applications should interact with a Distributed table instead of local replicated tables.

The Distributed table automatically routes queries and inserts to the appropriate replicas while hiding the underlying cluster topology.

Configuration Overview

Setting up replication requires several configuration files under:

/etc/clickhouse-server/config.d/

Each file serves a different purpose.

Configuration File	Purpose
`cluster.xml`	Defines shards and replicas
`keeper.xml`	Configures ClickHouse Keeper and RAFT
`zookeeper.xml`	Specifies Keeper endpoints
`macros.xml`	Defines shard and replica identifiers

After updating these configuration files, restart ClickHouse on every node before creating replicated tables.

Important Notes

cluster.xml is identical across all nodes.
zookeeper.xml is identical across all nodes.
keeper.xml contains node-specific server_id values.
macros.xml contains node-specific replica names.

Creating Replicated Tables

Once the cluster is configured and ClickHouse has been restarted on every node, create the database and tables.

Step 1 — Create the Database

CREATE DATABASE analytics
ON CLUSTER cluster_1S_3R;

Step 2 — Create the Local Replicated Table

CREATE TABLE analytics.orders_local
ON CLUSTER cluster_1S_3R
(
    order_id UInt32,
    customer String,
    amount Float64,
    order_date Date
)
ENGINE = ReplicatedMergeTree(
    '/clickhouse/tables/{shard}/orders_local',
    '{replica}'
)
ORDER BY order_id;

The placeholders:

{shard}
{replica}

are automatically replaced using values from macros.xml.

Step 3 — Create the Distributed Table

CREATE TABLE analytics.orders_distributed
ON CLUSTER cluster_1S_3R
AS analytics.orders_local
ENGINE = Distributed(
    cluster_1S_3R,
    analytics,
    orders_local,
    rand()
);

Applications should perform all inserts and queries using this Distributed table.

Verifying Replication

Insert sample records.

INSERT INTO analytics.orders_distributed VALUES
(1,'Alice',1200.00,'2024-01-01'),
(2,'Bob',450.00,'2024-01-02'),
(3,'Charlie',890.00,'2024-01-03'),
(4,'Diana',670.00,'2024-01-04');

Now query the local table from each node.

SELECT *
FROM analytics.orders_local
ORDER BY order_id;

Expected output on every replica:

order_id	customer	amount	order_date
1	Alice	1200.00	2024-01-01
2	Bob	450.00	2024-01-02
3	Charlie	890.00	2024-01-03
4	Diana	670.00	2024-01-04

Seeing identical data across all replicas confirms that replication is functioning correctly.

How Replication Works Internally

When an application inserts data into the Distributed table, ClickHouse performs the following sequence automatically:

Application
      │
      ▼
Distributed Table
      │
      ▼
Selected Replica
      │
      ▼
Writes Data Part
      │
      ▼
ClickHouse Keeper Updates Metadata
      │
      ▼
Remaining Replicas Fetch Data
      │
      ▼
Replication Complete

The process consists of these steps:

The Distributed table routes the insert to one replica.
That replica writes a new data part locally.
ClickHouse Keeper records the new data part.
Other replicas detect the update.
Replicas download the new part.
Keeper confirms successful synchronization.
Every replica now contains identical data.

This synchronization occurs automatically without requiring manual intervention.

Monitoring Replication

Monitoring replica health is essential for production clusters.

Query the system.replicas table.

SELECT
    database,
    table,
    replica_name,
    is_leader,
    is_readonly,
    total_replicas,
    active_replicas,
    queue_size
FROM system.replicas
WHERE table='orders_local';

Example output:

database	table	replica_name	is_leader	total_replicas	active_replicas
analytics	orders_local	replica_1	1	3	3
analytics	orders_local	replica_2	0	3	3
analytics	orders_local	replica_3	0	3	3

Healthy replication typically shows:

active_replicas = total_replicas
is_readonly = 0
queue_size = 0

Checking Replication Errors

To identify replication failures:

SELECT
    database,
    table,
    replica_name,
    last_exception
FROM system.replicas
WHERE last_exception != '';

Any returned rows indicate replication issues that require investigation.

Verifying ClickHouse Keeper

You can verify Keeper availability using:

echo "ruok" | nc 10.x.x.1 9181

Expected response:

imok

If Keeper does not respond, replication will eventually stop because replicas can no longer coordinate metadata.

Common Issues and Solutions

Issue	Likely Cause	Recommended Fix
Replica becomes read-only	Keeper unavailable	Verify Keeper connectivity
Replication queue continues growing	Network latency or firewall	Check network connectivity
Data isn't replicating	Incorrect ReplicatedMergeTree path	Verify ZooKeeper/Keeper paths
Lost Keeper quorum	Too many Keeper nodes offline	Restore quorum by bringing nodes back online

Performance and Operational Best Practices

To build a reliable replicated ClickHouse deployment:

Deploy an odd number of Keeper nodes (3 or 5) to maintain quorum.
Assign every Keeper node a unique server_id.
Give every replica a unique name in macros.xml.
Always execute DDL statements using ON CLUSTER.
Perform inserts through the Distributed table instead of local tables.
Monitor system.replicas regularly for replication lag.
Restart cluster nodes one at a time.
Ensure stable, low-latency connectivity between data centers.
Batch inserts to reduce replication overhead.
Continuously monitor Keeper health and replication queues.

When Should You Use Cross-Datacenter Replication?

Cross-datacenter replication is an excellent choice when your environment requires:

High availability
Disaster recovery
Multi-region deployments
Read scalability
Business continuity
Low-latency regional analytics
Fault-tolerant analytical platforms

Organizations operating globally often combine replicated tables with distributed queries to provide seamless analytics regardless of where users connect.

Conclusion

Cross-datacenter replication enables ClickHouse® to maintain synchronized copies of data across geographically distributed environments, improving availability, fault tolerance, and disaster recovery capabilities. By combining ReplicatedMergeTree, ClickHouse Keeper, and Distributed tables, organizations can build resilient analytical platforms that continue serving queries even when individual nodes or data centers become unavailable.

Although network latency and bandwidth should be considered when replicating across regions, following best practices such as batching inserts, maintaining a healthy Keeper cluster, monitoring replication queues, and using Distributed tables for application traffic helps ensure reliable and efficient synchronization.

For organizations requiring both high-performance analytics and resilient multi-region deployments, ClickHouse provides a scalable and robust replication architecture that minimizes operational complexity while maximizing availability.

What's the Difference Between RAG and Agent Memory?

gregor — Sun, 12 Jul 2026 13:44:17 +0000

What's the Difference Between RAG and Agent Memory?

RAG (Retrieval-Augmented Generation) retrieves relevant passages from a fixed document collection at query time and pastes them into the prompt. Agent memory stores what the agent has learned from interactions — corrections, preferences, decisions, behavioral patterns — and updates that knowledge over time. The distinction is not subtle: RAG is read-only retrieval from external corpora; agent memory is read-write learning with feedback loops, forgetting, and consolidation. RAG answers "find me a document about X"; agent memory answers "remember that we decided to use Vitest instead of Jest last week, and that you corrected me on the API endpoint last Tuesday."

The core difference

Property	RAG	Agent Memory
What it stores	Documents, passages, chunks from external corpora	What the agent learned from interactions — corrections, preferences, decisions
Read / write	Read-only at query time (the corpus is static)	Read-write (the agent writes new memories, updates, and deletes old ones)
Updates	Corpus changes when you add/remove documents; no learned updates	Memories are created, reinforced, decayed, and forgotten based on feedback
Persistence	Documents persist; retrieval results do not accumulate	Memories accumulate across sessions and improve over time
Learning	No learning — same query retrieves the same passage	Learns from corrections, feedback signals, and usage patterns
Forgetting	No forgetting mechanism — all documents remain equally retrievable	Supported by design — several systems apply time-based decay (ACT-R-inspired) so outdated memories lose retrieval strength
Provenance	Source document is the provenance	Each memory has provenance — who said it, when, in what context
Format	Vector embeddings in a vector store	Varies: vector store, knowledge graph, YAML files, agent state blocks

The distinction maps to a well-known one in cognitive science: semantic memory (general knowledge, facts — what RAG provides) vs episodic and procedural memory (what happened to you, what you learned to do — what agent memory provides). RAG gives the model access to a library. Agent memory gives it a notebook it writes in.

What RAG is (and what it does well)

RAG was formalized by Lewis et al. in 2020 ("Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks," NeurIPS 2020, arXiv:2005.11401). The architecture is simple: given a query, retrieve the top-k relevant passages from a document index, prepend them to the prompt, and let the model generate an answer conditioned on both the query and the retrieved context. A 2023 survey by Gao et al. (arXiv:2312.10997) catalogued the explosion of RAG variants — pre-retrieval, post-retrieval, modular pipelines — and confirmed the core pattern: retrieve, augment, generate.

RAG is excellent for question answering over known documents. If you have a corpus of PDFs, a product manual, a codebase, or a wiki — RAG lets the model cite specific passages from that corpus. It is the standard approach for "chat with your documents" use cases.

What RAG cannot do

RAG has four structural limitations for agent use cases:

1. No learning from interactions

RAG retrieves from a static corpus. If you correct the model — "actually, we use Vitest, not Jest" — the retrieval pipeline does not update. Next session, the model retrieves the same documents and may make the same mistake. The corpus is fixed; the model's behavioral knowledge does not accumulate. A 2024 survey of LLM-based agent memory mechanisms (Zhang et al., "A Survey on the Memory Mechanism of Large Language Model based Agents," arXiv:2404.13501) identified this as the fundamental gap: "memory designs are scattered across different papers" because RAG addresses retrieval, not learning.

2. No preference persistence

RAG cannot remember that you prefer tabs over spaces, that your database is PostgreSQL, or that you deprecated an API last week. These are not documents in a corpus — they are facts the agent learned from interacting with you. RAG has nowhere to put them.

3. No forgetting or decay

In RAG, all documents are equally retrievable forever. There is no mechanism to say "this fact is outdated" or "this preference changed." If you migrated from Jest to Vitest, both the old and new documentation sit in the index with equal standing. Agent memory systems can model forgetting explicitly — several projects adapt the ACT-R cognitive theory, applying time-based decay so outdated memories lose retrieval strength while recently-reinforced ones stay sharp (implementations vary: not every memory engine ships decay, but the architecture supports it, which RAG's does not).

4. No feedback loops

RAG retrieval is one-shot: query, retrieve, generate. There is no signal that says "that retrieval was helpful" or "that retrieval was irrelevant." Agent memory systems can close this loop: feedback signals (positive, negative, neutral) train the injection pipeline so recall quality improves with use. Not every engine implements feedback, but where it exists, the more you use it, the better it gets at surfacing the right memory at the right time.

What agent memory adds beyond retrieval

Agent memory systems perform four operations that RAG does not:

Capture — Extract facts, corrections, preferences, and decisions from the conversation as they happen. Not a document dump; structured memory items (the agent learned you prefer tabs, that the database is PostgreSQL, that the auth flow uses JWT).
Store — Persist those items outside the model in a format that survives session end. Formats vary: Mem0 uses a vector store, Letta uses agent state blocks, Zep uses a temporal knowledge graph, PLUR uses human-readable YAML files.
Retrieve (with context) — At the start of the next session, surface the right memories for the current context. Not all of them — that would overflow the window. The relevant ones, selected by hybrid search (BM25 + embeddings), activation strength, and feedback signals.
Update and forget — When a fact changes, update the memory. When a fact is wrong, correct it. When you want something deleted, delete it. Memories decay over time if not reinforced, so the system does not accumulate stale noise.

This is not theoretical. MemGPT (Packer et al., 2023, "MemGPT: Towards LLMs as Operating Systems," arXiv:2310.08560) demonstrated that treating memory like an OS manages memory tiers — core memory in the context window, archival memory retrieved on demand — dramatically improves agent performance on multi-session tasks. The key insight: agents need managed memory, not just more context.

Can you use both?

Yes, and many agent architectures do. RAG and agent memory serve different layers:

RAG handles the knowledge layer — what documents, code, and reference material the agent can access. You point it at your codebase, your docs, your wiki.
Agent memory handles the experience layer — what the agent has learned from working with you, what preferences it has accumulated, what mistakes it has been corrected on.

A coding agent might use RAG to search your repository for a function definition, and use agent memory to remember that you prefer functional style over OOP. The two systems are complementary, not competitive. The mistake is thinking RAG alone gives your agent memory — it gives your agent a library, but no notebook.

The landscape: who does what

Project	RAG?	Agent Memory?	Format
LangChain RAG	Yes (core feature)	Partial (memory modules, but basic)	Various module types
LlamaIndex	Yes (core feature)	Partial (chat history buffers)	Buffer, summary, vector
Mem0	No	Yes (memory layer)	Vector store
Letta (formerly MemGPT)	No	Yes (stateful agent OS)	Agent state blocks
Zep / Graphiti	No	Yes (temporal knowledge graph)	Knowledge graph
Cognee	Partial	Yes (graph + vector + relational)	Own data model
PLUR	No	Yes (engram engine + MCP)	Human-readable YAML (open format)

The key differentiator within agent memory is format openness. Mem0 and Letta are open-source (Apache-2.0) but store memories in opaque formats — vector embeddings or agent state blocks you cannot read in a text editor. PLUR (Apache-2.0, github.com/plur-ai/plur) stores memories as YAML files you can open, edit, diff, and version-control. The MCP (Model Context Protocol, specification 2025-11-25) makes the transport layer open; the memory format is the differentiator.

When to use which

If you need…	Use
Search and cite a fixed document corpus	RAG
Answer questions over your codebase, docs, or wiki	RAG
Remember user preferences across sessions	Agent memory
Learn from corrections and not repeat mistakes	Agent memory
Track how facts change over time	Agent memory (Zep for temporal, PLUR for decay-based)
Inspect, edit, and correct what the agent knows	Agent memory with open format (PLUR)
Both (search documents AND remember interactions)	RAG + agent memory (complementary)

FAQ

Is agent memory just RAG with extra steps? No. RAG retrieves from a static document collection at query time. Agent memory stores what the agent learned from interactions, updates it with feedback, and decays outdated entries. RAG is a read-only retrieval pipeline; agent memory is a read-write learning system with forgetting and consolidation.

Can RAG replace agent memory? Only if your agent never needs to remember preferences, corrections, or decisions across sessions. If your agent works in a single session or only queries fixed documents, RAG is sufficient. If your agent accumulates knowledge over time — learning your coding style, remembering architectural decisions, not repeating corrected mistakes — you need agent memory.

Can you use RAG and agent memory together? Yes. They serve different layers: RAG handles the knowledge layer (documents, code, reference material), agent memory handles the experience layer (what the agent learned from working with you). Many agent architectures combine both.

Is agent memory slower than RAG? Not necessarily. Both involve a retrieval step at query time. Agent memory adds a write step (capturing memories during the conversation) and a decay/feedback step (updating memory strength), but these are background operations that do not add latency to the inference path. Zep reports sub-200ms retrieval for its temporal knowledge graph (docs.getzep.com).

What is the ACT-R decay model in agent memory? ACT-R is a cognitive architecture from cognitive science that models how human memory decays over time. Several agent memory systems adapt it: memories that are not accessed lose retrieval strength, while memories that are reinforced (accessed or given positive feedback) gain strength. This prevents the memory store from accumulating stale noise — something RAG cannot do because all documents remain equally retrievable.

TuneWatch: A Private Space for the Entertainment We Love Together

Thierno Abdoulaye Diallo — Sun, 12 Jul 2026 13:37:52 +0000

This is a submission for the *Weekend Challenge: Passion Edition*.

What I Built

I built TuneWatch, a private collaborative media tracker for small groups.

TuneWatch gives friends, couples, families, and small communities a shared place to keep track of the entertainment they care about:

movies
anime
books
music

Users can create an account, choose a profile avatar, use a personal tracker, create private groups, invite other people with a code, add recommendations, rate entries, search their shared library, and view statistics based on real activity.

The idea is simple: the things we love are rarely enjoyed alone.

When I discover a great movie, finish an anime, read a memorable book, or hear a song I cannot stop replaying, I usually want to share it with someone. TuneWatch turns those scattered recommendations into one private and organized space.

Main features

Self-service account creation
Username and avatar setup
Personal tracking space
Private groups of up to five members
Invite codes
Real-time shared entries
Movies, anime, books, and music
Ratings, statuses, notes, and tags
Search
Group statistics
Mobile-first interface
Installable web application

The interface was designed around mobile use and inspired by the clarity, spacing, rounded surfaces, and comfortable touch targets found in Samsung One UI.

Demo

Live application

Open TuneWatch

A new visitor can create an account directly in the application, choose an avatar and username, and start using a personal tracker without requiring an administrator.

If you'd like to explore TuneWatch without creating a new account, you can use the demo account below.

Email

demo@tunewatch.app

Password

TuneWatch2026!

Video demonstration

Watch the TuneWatch demo

The demonstration covers:

Creating an account
Configuring a profile
Adding an entry
Searching the tracker
Creating and joining groups
Viewing statistics
Editing the profile

Code

The source code is available on GitHub:

View the TuneWatch repository

How I Built It

TuneWatch uses:

React
JavaScript
Firebase Authentication
Cloud Firestore
Firebase Hosting
Lucide icons

Firebase Authentication handles account creation and login.

Cloud Firestore stores user profiles, groups, memberships, invite codes, and media entries. Each group owns its own entries subcollection, and Firestore listeners keep the tracker synchronized in real time.

The application is organized into separate layers:

Pages
  ↓
Components
  ↓
Hooks
  ↓
Services
  ↓
Firebase

The hooks manage authentication, groups, and entries. Firebase operations remain inside dedicated service files, while the pages focus on the user interface.

Personal and shared tracking

Every new user receives a personal space so that TuneWatch remains useful even when used alone.

A user can later create or join additional groups. Selecting, creating, or joining a group immediately activates it and returns the user to the Tracker.

Real data instead of mock content

The Tracker, Search, Groups, Statistics, and Profile screens all use real Firebase data.

Statistics such as completed entries, planned entries, average rating, and favorite category are derived dynamically from the active group.

Mobile-first design

I wanted TuneWatch to feel like a mobile product rather than a desktop dashboard squeezed onto a phone.

That led to:

a persistent bottom navigation bar
large touch targets
rounded cards
bottom sheets for important actions
short and natural interface text
graceful empty states
a consistent visual hierarchy

The Hardest Parts

Secure group membership

Joining and leaving groups required more than updating an array.

Group membership is limited to five people, so joins use Firestore transactions to avoid race conditions. Security rules also ensure that users cannot arbitrarily modify another group's members or entries.

Keeping the active group consistent

TuneWatch supports both personal and shared spaces.

The application saves the active group in the user's Firestore profile and restores it after login. This keeps the experience continuous across sessions and devices.

Turning a web app into a mobile experience

The application was tested directly on a phone throughout development.

This exposed issues that were easy to miss on desktop, including touch target sizes, content hidden behind the navigation bar, inconsistent dialogs, caching, and the installed application's name and icon.

Connection to the Theme

The challenge theme is Passion.

For me, passion is not only the thing we love. It is also the need to talk about it, recommend it, remember it, and experience it with other people.

TuneWatch was built around that shared side of passion.

It is not a large public social network. It is a smaller and more personal space for the people whose recommendations actually matter to you.

Challenge Work

TuneWatch began as an earlier experimental tracker.

During the challenge period, I substantially rebuilt and completed the product experience, including:

the mobile navigation and five-screen structure
account creation and profile onboarding
selectable avatars
personal tracking spaces
group flows
dynamic statistics
Firebase Hosting deployment
the mobile-first visual system
installable application branding
the final demo and documentation

I am including this note to be transparent about the project's development history.

What I Learned

This project reinforced that a product is not finished when the main features technically work.

Small details had a major effect on the final experience:

where the user lands after joining a group
whether an empty Tracker feels welcoming
whether a dialog belongs to the same visual system
whether a username appears instead of a raw email
whether an installed application still says “React App”

Building TuneWatch required thinking about the full journey rather than isolated components.

What's Next

After the challenge, I would like to explore:

richer media metadata and cover artwork
more media categories
notifications
offline support
native Android and iOS versions
better group activity insights

Thank you for reading.

What would you track with your own TuneWatch group?