When planning a new digital project, one of the first questions you may have is: Website vs. Web Application — what’s the difference?

Although websites and web applications both run through a web browser, they are designed for different purposes. Understanding the difference can help you choose the right solution for your business.

What Is a Website?

A website is primarily designed to provide information or content to visitors.

Examples include:

• Business websites
• Portfolio websites
• Blogs
• News websites
• Restaurant websites
• Company websites
• Informational websites

Visitors typically browse pages and consume information rather than performing complex tasks.

For example, a business website may include:

Home → About → Services → Portfolio → Blog → Contact

The main goal is usually to inform visitors, build trust, and generate inquiries or sales.

What Is a Web Application?

A web application is a website that allows users to interact with data, tools, or business processes.

Instead of simply reading information, users can perform actions within the application.

Examples include:

• Online banking systems
• Customer portals
• Booking systems
• Project management tools
• Online marketplaces
• Employee dashboards
• CRM systems
• Inventory management systems

For example, an online booking application may allow a user to:

Create an account → Select a service → Choose a date → Make a payment → Manage the booking

This requires considerably more functionality than a standard informational website.

Website vs Web Application: Key Differences

Website Web Application

Mainly provides information

Designed for user interaction

Usually simpler functionality

More complex functionality

Visitors browse content

Users perform tasks

Often public-facing

May require user accounts

Usually easier to develop

Requires more development

Examples: blogs, company sites

Examples: dashboards, booking systems

When Do You Need a Website?

A traditional website is usually the right choice if your primary goal is to:

• Promote your business
• Showcase your services
• Display your portfolio
• Publish articles
• Provide company information
• Generate leads and inquiries

For many small and medium-sized businesses, a professionally developed website is all they need.

When Do You Need a Web Application?

A web application may be more appropriate when your business needs users to interact with your system or data.

You may need a web application if you want to:

• Create customer accounts
• Manage bookings
• Process complex orders
• Build a customer dashboard
• Manage inventory
• Automate business processes
• Connect multiple systems through APIs
• Provide different functionality to different users

In these situations, simply adding more plugins to a traditional website may not always be the best long-term solution.

Can a Website and Web Application Work Together?

Yes. Many businesses use both.

For example:

Public Website

Visitors can learn about your company, services, pricing, and contact information.

Web Application

Registered customers can log in to manage orders, bookings, invoices, or account information.

This approach allows a business to have a professional public presence while providing advanced functionality to customers or employees.

Originally published at https://www.wathsalakg.com on September 12, 2026.

Website vs Web Application: What’s the Difference? was originally published in CodeX on Medium, where people are continuing the conversation by highlighting and responding to this story.

I still remember how simple server management felt when I had only one server.

I would SSH in, run a few commands, check the logs, fix the problem, and move on.

Then one server became five.

Five became ten.

Eventually, we were managing more than 50 servers.

That is when I realized something.

The hard part of managing Linux servers is not Linux itself. It is remembering everything you need to do around Linux.

You need to remember commands.

You need to remember flags.

You need to remember where files are.

You need to remember which server you are connected to.

You need to remember how you checked something six months ago.

And when you do not remember, you search Google, ask AI, open another terminal, or switch to another tool.

I have spent years doing exactly this.

That is also why we built CtrlOps.

It Starts With a Simple Question: “Why Is My Server Slow?”

You get a message:

“The server is slow.”

You open your terminal.

Now you need to figure out what is happening.

You might want to check:

• CPU usage
• Memory
• Disk usage
• Running processes
• Services
• Application logs
• Nginx
• PM2
• Database

The actual problem was one sentence.

But solving it can mean remembering a lot of commands.

And that is only one server.

Managing One Linux Server Already Means Remembering a Lot

When you manage a Linux server, you quickly collect a long list of commands.

You need commands to:

• Check CPU
• Check memory
• Check disk
• Find large files
• Check running processes
• Check services
• Read logs
• Restart services
• Manage users
• Change permissions
• Move files
• Copy files
• Create backups
• Check security
• Monitor the server

The problem is not that these commands are impossible to learn.

The problem is that you do not use every command every day.

So when you need one after three months, you think:

“What was that command again?”

Then Google.

Then Stack Overflow.

Then documentation.

Then maybe AI.

And finally, you get back to the server.

That detour costs more than it feels like it does.

A study of 5,971 professional developers found it takes an average of 8.64 minutes to resume work after an interruption.

And IDE telemetry from 86 programmers found that only 10% of interrupted coding sessions resume within a minute.

Your brain does not care that you interrupted yourself.

Sometimes You Forget the Server Before You Forget the Command

This gets worse when you have multiple servers.

Before running anything, you might need to remember:

• Which server?
• What was the SSH command?
• Which SSH key?
• Is this production or staging?
• How do I check CPU?
• How do I check memory?
• How do I check disk?
• Where are the logs?
• Is a process eating resources?
• Is PM2 running?
• Is Nginx okay?
• Is the disk full?

Now the problem is not just remembering commands.

You are remembering server context.

And the more servers you manage, the harder this gets.

Then You Ask AI

This is probably what many of us do now.

You tell AI:

“Give me a command to check what is using disk space on Ubuntu.”

You get a command.

Great.

But there is still a problem.

AI does not automatically know your server.

It does not know:

• What applications you are running
• Which directories are important
• What services are critical
• What data you can safely remove
• What your production setup looks like

So you copy the command.

You read it quickly.

And you run it.

That can be fine for a simple read-only command.

But what happens when the command changes something?

Or deletes something?

Or restarts something?

Or modifies a production configuration?

That is where I do not want to blindly trust an AI-generated command.

I Don’t Want AI to Control My Server

I want AI to help me.

There is a difference.

If I tell AI:

“My disk is almost full. Help me find what is taking the space.”

I want AI to generate a command.

I want to see the command.

I want to understand what it does.

I want to know whether the command is safe.

And then I want to decide whether to run it.

That is the idea behind the AI Terminal in CtrlOps.

You explain the problem.

CtrlOps generates the command.

You can see the command and its explanation before running it.

Destructive operations are flagged before you decide.

You can review it.

You can edit it.

And the command does not run until you approve it.

The AI is helping you get the command.

You are still deciding what happens on your server.

Sometimes I Know the Command. Sometimes I Don’t.

I don’t want to pretend I never use the terminal.

I use it all the time.

Sometimes I know exactly what I want to run.

The problem is the other 20 percent of the time.

Maybe I remember,pm2but forget the exact command.

Maybe I know I need to search files, but forget the right flags.

Maybe I know the service name, but forget the systemctl command.

In those moments, CtrlOps can help with command suggestions directly in the terminal.

I can start typing and get suggestions instead of leaving the terminal to search for syntax.

Worth knowing: this part is plain autocomplete. It does not call the AI, and it does not need an API key.

That sounds small.

When you do it hundreds of times, it is not.

But Server Management Is More Than Commands

This is where things get interesting.

Even if I solve the command problem, I still have a lot of other work.

I need to manage files.

I need to check applications.

I need to read logs.

I need to monitor resources.

I need to check security.

I need backups.

And I need to do all of this again for every server.

So we started looking at the bigger problem.

“I Just Need to Change One File”

Maybe I need to:

• Upload a file
• Download a log
• Edit a configuration
• Rename something
• Move a folder
• Extract an archive
• Find a file

I can do all of this from the terminal.

But sometimes I just want to open the server and manage the files.

That is why CtrlOps has a File Manager.

I can browse the server, upload and download files, create folders, edit text files, rename files, and unzip archives without writing a single line of command

I can opennginx.conf, change the line, and hit Save.

The download, edit, and re-upload loop stops existing.

The goal is simple.

I want to manage the file, not think about the command.

“Is My Application Running?”

Someone tells me:

“The website is down.”

Now I need to check the application.

If I use PM2, I might need to check:

• Is the process running?
• Did it restart?
• Is CPU high?
• Is memory high?
• What do the logs say?
• Should I restart it?
• Should I reload it?

Here is the part that pm2 list will not tell you.

A process that has restarted 120 times looks exactly like a healthy one.

With the PM2 Manager, I can see the processes, CPU, memory, uptime, restarts, and logs in one place.

The restart count sits on the row, next to the last exit code.

I can also restart, reload, start, or stop the process.

Again, I am not trying to remove PM2.

I am trying to remove the unnecessary command memorization around PM2.

Then There Are Logs

Logs are another rabbit hole.

You know something is wrong.

Now you need to find the right log.

Maybe it is Nginx.

Maybe PM2.

Maybe the application.

Maybe a system service.

Then you need to search through it.

Log Management brings the logs into one place so I can search them, follow them live, download them, or clear them.

Every log is stamped with its size and when it was last written.

So instead of asking:

“Where is this log?”

I can start with the two files that changed in the last five minutes.

The one touched three minutes ago is usually where the problem is.

“Is the Server Under Pressure?”

The website is slow.

The application looks okay.

So what is happening?

I want to check:

• CPU
• Memory
• Disk
• Network

Infrastructure monitoring shows all of it live, refreshing every two seconds over SSH, with nothing installed on the server.

The top processes are listed and sortable, so I can find what is eating the box without rebuilding a ps aux pipeline from memory.

Now I can start with information instead of guessing.

Then There Is Security

Server security is another area where manual work adds up quickly.

You need to check things like:

• SSH configuration
• User access
• Sudo access
• Firewall
• Open ports
• Running services
• Other security settings

You can do this manually.

But how often will you actually remember to do a full audit?

Security Audits run 25 predefined checks over SSH and show findings, warnings, and a hardening score out of 100.

You also get a PDF you can send to a client.

Fix commands go through the same approval step as everything else.

So again:

Check first. Understand. Then approve the change.

And What About Backups?

Backups are easy to forget.

You create a script.

You schedule it.

You assume everything is fine.

Then one day you need the backup.

And you ask:

“Did the backup actually run?”

Scheduled backups are configured from one form, and every run keeps its log with the file count and the bytes moved.

So the answer to that question is a screen, not a guess.

Because having a backup script is one thing.

Knowing that your backup workflow is actually being managed is another.

All of This Is Still One Server

This is the part people often underestimate.

Let’s say you have one server.

You have:

• Terminal
• File management
• PM2
• Logs
• Monitoring
• Security
• Backups

You can manage all of that.

It takes time, but you can do it.

Now add another server.

Then another.

Then another.

Suddenly you have a completely different problem.

What Happens When You Have 10 Servers?

Now you need to remember:

• Which server belongs to which project?
• Which one is production?
• Which one is staging?
• Which one runs the database?
• Which SSH key should I use?
• Which terminal is connected to which server?
• Which server had the problem yesterday?
• Where are the logs?
• Which server needs the security audit?
• Which server has the backup issue?

And now you have terminals everywhere.

One terminal for this server.

Another for that server.

A different window for production.

Another tool for files.

Another tool for monitoring.

Another place for logs.

Another place for backups.

This is where server management becomes exhausting.

You are not just managing servers anymore. You are managing the tools around the servers.

This is also the gap between a tool that connects you to a server and one that helps you once you are there, which I have written about before.

We Know This Pain Because We Lived It

We have been running an IT service company for around five years.

We have managed more than 50 servers.

So we know this workflow very well.

We used the terminals.

We searched for commands.

We switched between tools.

We opened multiple SSH sessions.

We managed files manually.

We checked logs manually.

We monitored servers.

We handled backups.

We performed security checks.

And every time we added more servers, the same problems became bigger.

At some point, we asked:

“Why are we still doing all of this manually?”

That question led us to build CtrlOps.

So We Built CtrlOps

The idea was not to build another terminal.

The idea was to put the things we repeatedly needed into one place.

Now I can connect multiple Linux servers and manage them from the same application.

Instead of remembering which terminal belongs to which server, I can select the server I want to work on.

Each one opens in its own tab with its own connection, so a long build on one never blocks another.

Then I can use the tool I need.

Need a terminal? → Open Terminal.

Don’t know the command? → Ask the AI Terminal.

Need to manage files? → Open File Manager.

Need to check Node processes? → Open PM2 Manager.

Need to investigate an error? → Open Log Management.

Need to check server resources? → Open Monitoring.

Need to check security? → Run Security Audit.

Need to manage backups? → Open Backup Management.

The goal is not to give you another dashboard.

The goal is to reduce the number of things you need to remember.

What It Does Not Do

I would rather say this now than have you find out later.

It does not run one command across your whole fleet.

There is no broadcast or fan-out.

If firing the same command at twenty machines at once is your core need, Ansible is the right tool, and this is not it.

Backups copy files off the server.

They do not restore them, and they are not database-aware.

The security audit is a configuration audit and a hardening record.

It is not a vulnerability scanner, and it is not attested evidence for SOC 2 or ISO 27001.

And it does not make you a Linux engineer.

It removes the recall step, not the thinking.

One Server Is One Problem. Multiple Servers Change Everything.

When I started managing servers, I thought the hardest part would be learning Linux.

After managing more than 50 servers, I think differently.

The hard part is not knowing whether it df exists.

The hard part is remembering which server, which tool, which command, which file, which log, and which action, when you have many servers to manage.

That is the pain we experienced.

That is the reason we built CtrlOps.

How Do You Manage Your Servers Today?

I would genuinely like to know.

Do you still manage everything through SSH?

Do you have multiple terminal windows open all day?

Do you use different tools for monitoring, files, logs, backups, and security?

Or have you already found a workflow that makes multiple servers easy to manage?

Tell me what your setup looks like in the comments.

I am especially curious about the one command you look up every single time, no matter how many years you have been doing this.

Mine is still journalctl.

And if you want to see what we built from these problems, the 22 browser tools on our site are free with no sign-up, and the desktop app is a one-month trial and then $7 a month.

I am Hiren Kalariya, Co-Founder and CEO of TST Technology. I work on CtrlOps, a 100% local desktop app for managing multiple Linux servers over SSH. I write about the unglamorous parts of running infrastructure and building a product at the same time.

How to Debug a Linux Server Without Memorizing Every Command was originally published in CodeX on Medium, where people are continuing the conversation by highlighting and responding to this story.

An agent can change the architecture. That doesn’t mean it should be able to redefine the rules that verify the change.

One of the less obvious problems I’ve run into with coding agents isn’t that they make bad changes.

It’s that sometimes they make a perfectly reasonable change that invalidates one of the rules I’m using to check the project.

That’s a different problem.

Imagine a project has this rule:

All payment-provider access must go through PaymentAdapter.

An agent is asked to add support for another payment provider.

It looks at the existing code and decides that the current adapter isn’t quite right. It wants to introduce a new abstraction.

The resulting change crosses a boundary that the project currently protects.

The checker reports a violation.

So what should happen next?

The obvious automation is:

1. agent changes the code;
2. check fails;
3. agent changes the rule;
4. check passes.

Technically, everything worked.

But the system has a problem: The thing being checked was allowed to change the conditions of the check.

That made me much more interested in the difference between changing the code and changing the rules around the code.

The dangerous loop

The simplest version looks like this:

agent
  ↓
change code
  ↓
verification
  ↓
failure
  ↓
agent changes policy
  ↓
verification
  ↓
pass

There is nothing obviously broken here.

The agent might even have a good reason for changing the policy.

The problem is that the verification boundary has disappeared.

A policy is supposed to tell the system what has to remain true.

If the same actor that made the change can also redefine what “true” means, a successful verification doesn’t tell you very much.

It’s just a moving target.

And this isn’t specific to architecture.

You could do the same thing with:

maximum service size = 300 lines

The agent produces a 420-line service.

The check fails.

The agent changes the limit to 500.

The check passes.

Or:

module A cannot import module B

The agent needs the dependency.

It changes the rule.

The import is now allowed.

Again, maybe that’s the right architectural decision.

But those are two separate decisions:

• The implementation changed.
• The policy changed.

They shouldn’t become one operation just because the same agent proposed both.

Not every policy violation is actually a mistake

This is where it gets more interesting.

I don’t want an architecture checker that treats every violation as proof that the agent did something wrong.

Sometimes the agent really should change the architecture.

Suppose an application has:

Checkout
   ↓
PaymentAdapter
   ↓
Stripe

And I decide that the product is getting large enough that payment workflows deserve their own domain boundary:

Checkout
   ↓
PaymentService
   ↓
PaymentAdapter
   ↓
Stripe

The change introduces new files.

Some imports move.

Some old boundaries disappear.

New ones appear.

A strict checker could report a pile of violations.

That doesn’t mean the change is bad.

It means the current policy describes the old architecture.

This distinction matters.

A policy isn’t supposed to prevent architecture from ever changing.

It is supposed to make architecture changes explicit.

Proposal and approval are different things

This led me to a fairly simple rule: An agent should be able to propose a policy change, but it shouldn’t automatically be able to approve that policy change.

For example:

Current policy:

Payment provider access must go through PaymentAdapter.

The agent can say:

Proposed change:

Allow PaymentService to depend directly on a new internal
PaymentProvider interface.

Reason:
The current adapter boundary prevents the new workflow
from sharing transaction state correctly.

That’s useful.

The agent has done the hard reasoning.

It has identified the existing constraint.

It has explained why the constraint may no longer fit.

But the proposal should remain a proposal.

The important part is that the authority approving the policy change is separate from the agent that authored the change.

Otherwise the system can silently move the goalposts.

This is the same reason I don’t want approval in the prompt

A prompt can say:

Never deploy without approval.

That’s useful instruction.

It’s not much of a control if the same process can modify the configuration that defines what counts as an approved deployment.

The more autonomous the agent becomes, the more these distinctions move out of the prompt and into the environment around it.

The agent should be able to reason about the policy.

It should be able to request a policy change.

It should be able to explain the change.

The actual enforcement shouldn’t depend on the agent remembering to follow its own instructions.

A policy change should leave a trail

Once policy becomes a real project artifact, another problem appears.

You need to know what the policy was when the original change was checked.

Otherwise you can end up with a strange situation where today’s successful verification only makes sense because yesterday’s policy was replaced.

That’s why I like keeping policy changes explicit and versioned.

Something like:

project state
    ↓
policy revision 17
    ↓
agent proposes architecture change
    ↓
verification fails under policy revision 17
    ↓
policy proposal
    ↓
approval
    ↓
policy revision 18
    ↓
verify change again

Now there are two separate facts:

1. The change passed under policy revision 18.
2. Policy revision 18 was itself approved.

That’s much more useful than simply seeing a green check.

The old policy still matters

There’s another subtle point here.

Suppose an agent changes the rule and then verifies the same diff against the new rule.

You can no longer tell whether the original change violated the previous policy.

So I want the system to preserve the distinction between:

what the project allowed before the change

and:

what the project allows after the change

This becomes especially useful when investigating a change later.

You can ask:

• Why did this dependency become allowed?
• Was it always allowed?
• Was there an explicit exception?
• Did a policy revision happen at the same time?
• Who approved it?
• What evidence led to the change?

Those questions are much harder to answer when policy is just another mutable config file.

Temporary exceptions are different again

Sometimes the policy is fine.

The violation is temporary.

For example:

All persistence access must go through Repository.

But I’m in the middle of a migration.

I don’t want to remove the rule.

I just need one known exception for two weeks.

That’s not really a policy change.

It’s a waiver.

And I think treating it as a different object makes the whole system easier to reason about.

A useful waiver has at least:

owner
reason
scope
expiry

So instead of:

remove the rule

you get:

waive this finding until 2026-12-28

owner: platform-team
reason: repository migration

The rule stays.

The exception expires.

That’s a very different thing from changing the architecture policy permanently.

Baselines solve a different problem

I also don’t want to confuse waivers with baselines.

A baseline answers:

This violation already existed.

A waiver answers:

This active violation is intentionally allowed for a limited time.

And a policy change answers:

We changed what the project considers acceptable.

Those are three different states.

That separation might sound overly precise.

In practice, it makes the tool much more useful.

A real codebase can have old architectural debt.

It can have temporary migration exceptions.

And it can deliberately evolve its architecture.

If all three become “ignore this finding”, you lose important information.

What the agent should actually do

This doesn’t mean agents have to stop making architectural changes.

Quite the opposite.

I want them to do more.

A useful agent flow could look like this:

requirement
    ↓
agent plans change
    ↓
implementation
    ↓
deterministic verification
    ↓
failure
    ↓
agent explains why
    ↓
policy proposal / waiver proposal
    ↓
approval
    ↓
verification against new state

The agent can drive most of that workflow.

It can inspect the repository.

It can understand the requirement.

It can implement the refactor.

It can identify the policy that stopped the change.

It can prepare the evidence for a policy proposal.

It can even tell me that the current architecture appears to be the problem.

What it shouldn’t get is an invisible path from:

my change failed

to:

therefore my own change is now allowed

This also changes what “autonomous” means

I’ve started thinking that autonomy isn’t really one switch.

An agent can have permission to:

• read the repository;
• modify source files;
• run tests;
• inspect dependencies;
• propose policy changes;

without having permission to:

• approve those policy changes;
• remove its own enforcement;
• extend a temporary waiver indefinitely;
• change the authority that verifies it.

That gives you a more useful permission model than simply:

autonomous = yes/no

Different operations can have different authorities.

And that matters more once the agent is running for a long time or can delegate work to other agents.

The verifier should not care who made the code change

There’s another distinction here that I find useful.

Verification should primarily answer:

Does the current change fit the current approved policy?

It doesn’t need to decide whether the author was:

human
Claude
Codex
Cursor
another agent
automation

That’s a separate concern.

The verifier checks the state.

The policy layer defines the constraint.

The authority layer controls who can change the constraint.

Keeping those pieces separate makes the system much easier to reason about.

This is what I started building into Guard

This distinction ended up affecting the design of Codapult Guard quite a bit.

Guard already had the idea of:

facts
  ↓
policy
  ↓
verification

But that isn’t enough when policy itself can change.

So I started treating policy changes as first-class operations.

Guard can discover project facts and prepare proposals.

A project can explicitly approve them.

For protected projects, policy approval can require a distinct actor rather than allowing the authoring agent to approve its own proposal.

The same idea now applies to waivers.

A waiver is not just “ignore this finding forever.”

It has an owner, reason and expiry date.

When the expiry is reached, the finding becomes active again.

That gives the project three useful things:

policy
exception
history

instead of one growing collection of ignored warnings.

It also makes agent integration more useful

MCP makes this distinction especially important.

An agent can ask Guard:

What policy applies here?

or:

What did this change affect?

or:

Why did verification fail?

or:

What policy change would be needed for this refactor?

Those are useful questions.

But I don’t want the agent to receive:

Change policy until verification passes.

That isn’t really verification anymore.

The MCP layer should expose the information and operations the agent needs without quietly giving it the authority to redefine the system around itself.

That’s a much more interesting role for project-aware tooling than simply adding another set of commands to an agent.

The rule can change. That isn’t the problem.

I don’t think architectural rules should be permanent.

Projects change.

Requirements change.

Teams change.

The shape of the system changes.

A rule that made perfect sense six months ago might become actively harmful.

The mistake is treating policy change as an implementation detail.

Changing:

src/payments/StripeAdapter.ts

and changing:

payment-provider-access

are fundamentally different operations.

One changes the system.

The other changes what the system is allowed to become.

Once an agent can perform both, they need separate boundaries.

I’m less interested in stopping agents than in making their authority explicit

The goal isn’t to make agents weaker.

I actually want agents to make bigger changes.

But bigger changes require clearer boundaries.

The more of the implementation I delegate, the more I care about questions like:

• What can the agent change?
• What can it propose?
• What can it approve?
• What evidence does it have to provide?
• What policy was active when the change was checked?
• Was the exception temporary?
• Who approved the exception?
• Can the agent change the thing that verifies it?

Those questions aren’t really about whether the model is smart enough.

They’re about the architecture around the model.

And that’s probably the part that becomes more important as coding agents become capable of doing more work without waiting for a human after every step.

I don’t want the agent to be afraid of the rules.

I want it to understand them.

I want it to be able to challenge them.

I want it to be able to propose better ones.

But I don’t want it to be the final authority on whether its own change should become the new rule.

The code can change.

The architecture can change.

Even the policy can change.

Those changes just shouldn’t all happen under the same authority.

The Agent Shouldn’t Be Able to Approve Its Own Rules was originally published in CodeX on Medium, where people are continuing the conversation by highlighting and responding to this story.

The mock was correct when it was written. Nobody disputes that part. What happens after is the problem. The upstream payment service ships a release. The inventory service updates how it handles out-of-stock responses. The notification service changes its error format for invalid addresses. None of these changes come with an automatic update to the mocks representing those services in the downstream team’s test suite. The mocks keep returning what they were configured to return. The tests keep passing. The divergence between what the mock returns and what the real service currently returns accumulates without any signal.

Dependency mocking accuracy degradation is not a dramatic failure. It is a slow drift that makes test results progressively less trustworthy without making them visibly wrong.

Why Tests Keep Passing While Accuracy Drops

The thing that makes mock drift hard to catch is that the tests do not know they are running against stale assumptions. An assertion written against a mock response passes when the mock returns that response correctly. Whether the mock response still reflects current real service behavior is entirely outside what the assertion checks.

Coverage metrics cannot catch this. A test suite with ninety percent coverage and three-month-old mocks reports the same coverage number as one with current mocks. Pass rates cannot catch it either. The test passed- against its own expectations, which have not changed, even as the real service has.

The gap surfaces at production. An order fails because the payment service started returning a different charge object structure after its last deployment. The test that covered this interaction passed because it ran against a mock that returned the old structure. No metric flagged the mock as stale. No alert fired when the payment service deployed. The first signal was a failed order.

What Creates the Drift

Upstream deployments are the event that creates accuracy risk. Every time an upstream service deploys, there is a chance something it returns has changed. Not every deployment introduces a behavioral change that affects downstream mocks, but tracking which ones do requires either reading every changelog carefully or having a mechanism that catches the changes automatically.

Most teams do neither consistently. The developer who wrote the mock is three projects removed from it. The team consuming the upstream service has no channel through which deployment notifications arrive. Changelogs accumulate unread. The upstream service ships on its own schedule and the mock accumulates distance from it.

The other factor is how the mock was created. Mocks built from API documentation encode what the documentation said at authoring time. Nobody writes API documentation after the implementation ships. It gets written before, updated inconsistently, and left alone when things change in ways that feel too minor to document. A field that got renamed during a refactor. A format that was deprecated but still comes back on certain request paths. A property that appeared after a schema migration because the database started returning it. None of that shows up in what the mock was built from.

What Actually Keeps Mocks Current

Waiting for failures is the most common maintenance approach. A production incident reveals the stale mock. Someone updates it. The cycle repeats. What this model misses is everything between the upstream deployment that created the accuracy risk and the downstream failure that eventually surfaced it- days, sometimes weeks, of tests passing against assumptions the real service had already moved past. For drift that does not cause test failures, because the assertions pass against the old behavior even after the real service changed- the reactive approach never triggers at all.

The alternative trigger is the upstream deployment itself. Not the downstream failure it eventually causes. When the payment service deploys to staging, that event should be what prompts a check of the mocks representing payment service behavior- not the next production incident involving payment processing. This is a different architectural relationship between upstream deployments and downstream test maintenance. CI/CD webhook integrations and shared event subscriptions make it achievable. Most teams have not built it because the trigger for mock maintenance has always been a failure, not a deployment.

Recording sessions against real staging services change where mock content comes from. Instead of a developer authoring what the upstream service should return, a session against the real service captures what it actually returns for the request patterns the downstream service sends. The mock reflects observed real behavior rather than a developer’s reading of documentation. After the upstream service deploys a new version, a new session against the updated staging service captures current behavior. Comparing the previous session’s output against the new one surfaces what changed- which fields appeared or disappeared, which types shifted -without the developer needing to know in advance that anything changed.

This approach does not eliminate maintenance. It changes what maintenance requires. Instead of reading changelogs and manually updating mock files, the developer reviews a diff between observed past behavior and observed current behavior. The diff is the input they need to decide whether application code needs updating alongside the mock refresh.

The Metric That Would Actually Surface This

Mock accuracy does not have a standard metric in most testing frameworks. There is no dashboard showing that a mock was last validated six months ago against a service that has deployed dozens of times since. That information exists- it could be derived from deployment logs and mock metadata, but most teams do not track it.

The closest proxy is production failures traced to integrations the test suite claimed to cover. Not failures from missing tests. Failures where a test existed, the mock existed, the test passed, and production still broke. Tracking this separately from overall production failure rate reveals the proportion of production failures that came from mock accuracy gaps rather than from code defects or missing coverage.

Teams that track this number discover it is not small. A meaningful share of their production integration failures were preceded by passing tests against mocks that no longer reflected current dependency mocking reality. That share does not shrink by adding more tests. It shrinks by changing when and how the existing mocks get updated.

Why Dependency Mocking Accuracy Degrades Over Time and What to Do About It was originally published in CodeX on Medium, where people are continuing the conversation by highlighting and responding to this story.

For years, even the smallest C# program required a solution file, a project file, and a folder structure.

While Python and JavaScript developers could create a single file and run it in seconds, .NET developers had to create a solution and add a csproj file just to test an idea.

That changed with .NET 10, which introduced file-based apps.

Now you can run a C# file directly with dotnet run.

And in April 2026 in .NET 11 Preview 3 we received a support for using multiple files in file-based apps with the #:include directive.

This finally makes C# a real option for scripts, automation, internal tooling, and quick prototypes — without the overhead of a full project.

In this post, we will explore:

• What Are File-Based Apps in .NET
• Adding NuGet Packages and SDKs with Directives
• Splitting File-Based Apps Across Multiple Files
• Building an HTTP Health-Check Tool
• Building a Minimal API with EF Core and SQLite
• Converting a File-Based App to a Full Project

Let’s dive in!

👉 Read original article on my newsletter: https://antondevtips.com/blog/building-file-based-apps-in-dotnet-with-multi-file-support

What Are File-Based Apps in .NET

Traditionally, every C# application required three things:

• Solution file (*.sln)
• Project file (*.csproj)
• Source code (*.cs).

Even for a 10-line script, you had to create a new solution, add a project with dotnet new console, wait for the scaffolding to finish, and only then write your actual code.

Starting with .NET 10, you can skip all of that.

You can create a single .cs file and run it directly:

dotnet run main.cs

That’s it. No project file. No solution file. Just one file.

This puts C# on equal footing with Python, JavaScript, Node.js, and other scripting languages.

For CLI utilities, automation tasks, and one-off tools, this completely changes the workflow.

Let’s see the simplest possible example. Create a file called hello.cs:

Console.WriteLine("Hello from a file-based app!");
Console.WriteLine($"Today is {DateTime.Now:dddd, MMMM d, yyyy}");

Then run it:

dotnet run hello.cs

Notice there is no Main method, no class Program, no using statement.

File-based apps build on top of top-level statements (introduced in C# 9) and implicit usings, so you can write code as if you were in a script.

Behind the scenes, the .NET CLI compiles your file in a temporary location and runs the resulting binary.

The first run takes a moment, but subsequent runs are cached and fast.

I’ve used this many times in the last year for small tasks I would have otherwise written in Python (or created a solution project):

• Quick data transformations on JSON or CSV files
• Calling internal APIs to verify a deployment
• Running test scripts
• Parsing log files to extract patterns

Adding NuGet Packages and SDKs with Directives

A real script usually needs more than the BCL.

You probably want JSON parsing, HTTP calls, or database access.

File-based apps support special # directives at the top of your file to declare dependencies.

The #:package Directive

Use #:package to reference any NuGet package:

#:package Newtonsoft.Json@13.0.3
 
using Newtonsoft.Json;
 
var data = new { Name = "Anton", Year = 2026 };
var json = JsonConvert.SerializeObject(data, Formatting.Indented);
Console.WriteLine(json);

The format is #:package PackageName@Version.

The .NET CLI restores the package on first run, just like it would for a regular project.

The #:sdk Directive

Use #:sdk when you need a specific SDK, such as the Web SDK for ASP.NET Core:

#:sdk Microsoft.NET.Sdk.Web
 
var builder = WebApplication.CreateBuilder();
var app = builder.Build();
 
app.MapGet("/", () => "Hello from a single-file API!");
 
app.Run();

By default, file-based apps use Microsoft.NET.Sdk (the standard SDK).

Switching to Microsoft.NET.Sdk.Web unlocks ASP.NET Core types like WebApplication without any project setup.

The #:project Directive

If you need to call into an existing project (for example, a shared class library), use #:project:

#:project ../MyLibrary/MyLibrary.csproj
 
using MyLibrary;
 
var calculator = new Calculator();
Console.WriteLine(calculator.Add(2, 3));

This is helpful when you have a class library and want to write a quick tool that uses it, without creating yet another console project.

👉 Read original article on my newsletter: https://antondevtips.com/blog/building-file-based-apps-in-dotnet-with-multi-file-support

Building File-Based Apps in .NET: A Complete Guide With Multi-File Support was originally published in CodeX on Medium, where people are continuing the conversation by highlighting and responding to this story.

Arbiter Guide Theory • Day 11 | Why Java’s catch can only terminate, where checked exceptions came from, why finally is copied into every exit, and how try-with-resources becomes nested handlers in the bytecode

An exception rises through the call stack, nested resource brackets close from the inside out, and a handler table decides where control lands.

Before we begin, here’s the source code for today’s lesson:

class NegativeAmountException extends Exception {
    public NegativeAmountException(String message) {
        super(message);
    }
}

class DataFormatException extends Exception {
    public DataFormatException(String message) {
        super("Data Format Exception: " + message);
    }
}

class DataCorruptionException extends RuntimeException {
    public DataCorruptionException(String message) {
        super("Data Corruption Exception: " + message);
    }
}

class TrackedResource implements AutoCloseable {
    private String name;
    
    public TrackedResource(String name) {
        this.name = name;
    }

    @Override
    public void close() {
        System.out.println("Closing " + name);
    }

    public void process(int code) throws DataFormatException, DataCorruptionException {
        if (code == 1) throw new DataFormatException("Code = " + code);
        else if (code == 2) throw new DataCorruptionException("Code = " + code);
        else System.out.println("Processed " + code + " in " + name);
    }
}

public class java_11Exceptions {
    public static void main(String[] args) {
        try {
            int result = withdraw(100, 40);
            System.out.println("Result: " + result);
        } catch (NegativeAmountException e) {
            System.out.println(e.getMessage());
        } finally {
            System.out.println("Attempt finished.");
        }

        try {
            int result = withdraw(100, -10);
            System.out.println("Result: " + result);
        } catch (NegativeAmountException e) {
            System.out.println(e.getMessage());
        } finally {
            System.out.println("Attempt finished.");
        }

        System.out.println();

        try (
            TrackedResource tr1 = new TrackedResource("Tracked Resource 1");
            TrackedResource tr2 = new TrackedResource("Tracked Resource 2");
        ) {
            tr1.process(0);
        } catch (DataCorruptionException e) {
            System.out.println(e.getMessage());
        } catch (DataFormatException e) {
            System.out.println(e.getMessage());
        }

        try (
            TrackedResource tr1 = new TrackedResource("Tracked Resource 1");
            TrackedResource tr2 = new TrackedResource("Tracked Resource 2");
        ) {
            tr1.process(1);
        } catch (DataCorruptionException e) {
            System.out.println(e.getMessage());
        } catch (DataFormatException e) {
            System.out.println(e.getMessage());
        }

        try (
            TrackedResource tr1 = new TrackedResource("Tracked Resource 1");
            TrackedResource tr2 = new TrackedResource("Tracked Resource 2");
        ) {
            tr1.process(2);
        } catch (DataCorruptionException e) {
            System.out.println(e.getMessage());
        } catch (DataFormatException e) {
            System.out.println(e.getMessage());
        }
    }

    public static int withdraw(int balance, int amount) throws NegativeAmountException {
        if (amount < 0) {
            throw new NegativeAmountException("Amount cannot be negative: " + amount);
        }
        return balance - amount;
    }
}

The Guide article for this lesson showed what Java does with exceptions: finally always runs, the parent class decides checked vs. unchecked, and try-with-resources closes in reverse order before catch runs. This article asks why those are the rules, and where each one came from.

This is Day 11 of my Arbiter Learning Journey, where I’m learning Java from the ground up before eventually building Arbiter, a complete microservices-based test management platform. The practical version of today’s lesson is in the Day 11 Guide.

In Day 10 Guide Theory, the subject was compiled patterns, Thompson’s automata, and a strict > that ignored ties. This time the machinery is different, but the habit is the same: ask what the language promises, and then check that promise against evidence. Where I could, the evidence below is the compiler's own output, not my description of it.

(A note on ordering: Day 10 closed by previewing Sets. Today’s lesson file is Exceptions, so Sets get deferred one more slot.)

Why Failure Needed Its Own Control Flow: Goodenough’s Problem

Before throw existed as a mechanism, failure had to travel inside return values, and the paper that asked for a better notation

Look at withdraw:

public static int withdraw(int balance, int amount) throws NegativeAmountException {
    if (amount < 0) {
        throw new NegativeAmountException("Amount cannot be negative: " + amount);
    }
    return balance - amount;
}

It could have been written another way: return -1 for an invalid amount and make every caller check. But -1 is an int, the same type as a legitimate result, so a caller who forgets the check treats the failure as data. The failure disappears into the arithmetic.

John B. Goodenough took that problem seriously in “Exception Handling: Issues and a Proposed Notation,” published in Communications of the ACM 18(12) in December 1975. The paper doesn’t just propose a keyword. It frames exception handling as a design question with distinct choices, and it uses two terms that still organize the field: termination (the operation that raised the exception ends) and resumption (control returns to the point of the raise after the handler finishes). It even sorts exceptions by which of those the handler is allowed to do: one class must terminate, one must resume, and one leaves the choice to the handler.

Everything in today’s lesson sits on that foundation. throw new NegativeAmountException(...) moves the failure out of the data channel and into a separate control channel the compiler and runtime can see.

Termination, Not Resumption: What catch Can and Cannot Do

Java sits on one side of Goodenough’s divide, and the same side as CLU

Java picked a side. Once an exception is thrown, the code that threw it does not continue. The catch block runs, and control then continues after the whole try statement, never back at the throw point.

The first output of the lesson shows this. The second withdraw call throws, and the line System.out.println("Result: " + result); right after it never runs. The output for that attempt contains the exception message and Attempt finished., with no Result: line at all. I checked this in isolation as well: the statement after the throwing call is simply skipped.

The termination model has a well-documented relative. Barbara Liskov and Alan Snyder’s “Exception Handling in CLU” (IEEE Transactions on Software Engineering, SE-5(6), November 1979) describes a single-level termination model in which the signalling procedure’s activation ceases to exist. I’m not claiming Java copied CLU. I’m pointing out that both landed on the same side of Goodenough’s divide, for a reason you can read straight off the lesson: if the failing code were resumed, withdraw would need to return a value after a rejected amount, and there is no sensible value to return.

Checked vs. Unchecked: A Declaration Lineage and an Argument

CLU’s headers, Java’s throws, and the engineer who left checked exceptions out of C#

The lesson’s two custom exceptions differ in one word:

class NegativeAmountException extends Exception { ... }        // checked
class DataCorruptionException extends RuntimeException { ... } // unchecked

The Java Language Specification defines the split structurally (§11.1.1): the checked exceptions are Throwable and its subclasses, except RuntimeException, Error, and their subclasses. That's why there's no keyword. The class hierarchy is the declaration.

The idea of listing exceptions in a signature has a clear ancestor. In CLU, the Liskov and Snyder paper describes procedure headers that must name the exceptions a procedure may signal, which allows static checking. Java’s throws clause does a similar job. In today's code, process(...) throws DataFormatException, DataCorruptionException is that header.

The idea also has a famous critic. In an interview with Bruce Eckel and Bill Venners (held July 30, 2003, published August 18 as “The Trouble with Checked Exceptions”), Anders Hejlsberg, the lead architect of C#, gave two arguments against the feature. The first is versioning: adding a new checked exception to a method’s throws clause in a later release breaks every existing caller, much like changing a published interface. The second is scalability: in a large system built from many subsystems, declared exceptions pile up, and developers work around them with catch-all declarations or empty catch blocks.

Both arguments can be read off today’s code. Suppose process later gained a third checked exception. Each of the three try blocks in main would stop compiling until it got a new catch or throws. That is Hejlsberg's versioning point, in miniature. And the reason DataCorruptionException can be declared or not, as the Guide article showed, is that unchecked exceptions opt out of the whole system. The lesson uses both kinds side by side, which is a fair way to see the trade-off yourself.

finally Is Copied, Not Called: What javac Does With Your Always Block

Goodenough split cleanup by path; the compiler splits it back out

Goodenough’s paper treats cleanup as a first-class concern. It introduces a CLEANUP exception that runs before an operation is terminated abnormally, and an ENDED exception for normal completion. Two paths, two mechanisms.

Java’s finally merges them into one block you write once. But the block isn't a subroutine the runtime calls. I disassembled the lesson with javap -c (JDK 21, so exact offsets may differ on other compilers) and the string Attempt finished. appears six times in main's bytecode, three times per try/finally statement. For the first try:

• offset 20–25: after the try body completes normally
• offset 42–47: after the catch handler completes
• offset 53–59: in a catch-any handler, followed by aload_2 and athrow, which rethrows whatever arrived

The compiler pasted the finally body onto each exit path. The exception table makes the third path precise:

from  to  target  type
   0  20      31  Class NegativeAmountException
   0  20      53  any
  31  42      53  any

Read it as: if something is thrown between offset 0 and 20, jump to 31 when it’s a NegativeAmountException, otherwise jump to 53. The third row is the surprising one. Offsets 31–42 are the catch body itself, and an exception thrown inside the catch block also routes to 53. So finally runs even when the handler itself fails. The table doesn't just say finally runs. It says which ranges of code it covers.

RAII, Reinvented as a Block: Where Try-with-Resources Comes From

Stroustrup’s destructors, Java 7’s AutoCloseable, and a nesting the compiler builds for you

C++ solved cleanup with the object’s lifetime. The technique was developed between 1984 and 1989, mostly by Bjarne Stroustrup and Andrew Koenig, and Stroustrup named it resource acquisition is initialization (RAII) in The Design and Evolution of C++ (1994). A local object’s destructor runs when its scope ends, and locals are destroyed in the reverse of the order they were constructed.

Java doesn’t destroy objects at scope end, so it needed a block form instead. Java SE 7 introduced both the try-with-resources statement and the java.lang.AutoCloseable interface. Oracle's own write-up of the feature names the problem it fixes: with hand-written try/finally, a close() that throws while another exception is already in flight can replace the original, so the root cause is lost. Java 7 added addSuppressed() and getSuppressed() to Throwable so the close failure can be attached instead of hiding the real one.

Here’s the part I wouldn’t have guessed. Reverse order isn’t a rule the runtime enforces. It falls out of nesting. The exception table for the first try-with-resources block:

from  to  target  type
 154 159     166  Class java/lang/Throwable
 167 171     174  Class java/lang/Throwable
 144 184     191  Class java/lang/Throwable
 192 196     199  Class java/lang/Throwable
 134 207     210  Class DataCorruptionException
 134 207     224  Class DataFormatException

Offsets 154–159 are tr1.process(0), wrapped in a handler that closes tr2. That whole construct sits inside the range 144–184, which is wrapped in a handler that closes tr1. So the compiler turned two flat declarations into two nested try blocks, with tr2 innermost. Inner handlers run before outer ones, so tr2 closes first. Stroustrup's reverse-destruction rule and Java's reverse-close order are the same idea, reached by different mechanisms.

The handlers also contain the suppression logic. At offset 174–179 the bytecode calls Throwable.addSuppressed, and the string addSuppressed appears six times in main, two per resource block. That's the compiler writing the "close failed while handling another failure" code you never have to.

One more detail from the source: TrackedResource.close() declares no throws clause. That matters, because AutoCloseable.close() itself declares throws Exception. I tested the difference: declaring the resource as plain AutoCloseable r = new T() fails to compile with unreported exception Exception ... from implicit call to close(). The lesson compiles because the variables are typed as TrackedResource, whose close() narrows the signature to throw nothing.

Why catch Runs After Close: The Handler Table's Ordering

The bytecode makes the Guide article’s surprising output a structural fact

The Guide article reported the strangest line of the output: both Closing lines print before the catch message. In the table above, the last two rows say why. The catch entries cover offsets 134–207, the whole region, including both resource handlers. The inner Throwable handlers close their resource and then rethrow (athrow at offsets 183 and 206, both inside 134–207). The rethrown exception lands in the outer range, and then the catch handlers at 210 and 224 fire.

So “resources close before catch” isn’t a special rule. It’s what you get when catch is the outermost handler and each resource handler rethrows into it.

It also explains why you can’t touch tr1 from the catch block. At the language level the resource variable is scoped to the try body (JLS §14.20.3), and I confirmed that referencing it from catch fails with cannot find symbol. The bytecode agrees: the handler at offset 210 begins with astore_1, storing the exception in local slot 1, the same slot tr1 used inside the block.

What the Repeated Lines Prove

A counting argument: six resources opened, six closed, on three different paths

The program opens two resources in each of three try blocks, so six TrackedResource objects exist in total. The output contains six Closing lines. And the three blocks take three different paths: a normal exit, a checked exception, an unchecked exception.

That is the guarantee, stated as a count: every resource that was successfully opened is closed exactly once, on every path. The table shows why it holds. Each resource has a close() call on its normal exit and a handler on its exceptional exit, and the handlers for different resources cover different, nested ranges, so no path escapes without passing through one.

It’s worth stating what this does not prove. It shows the close happens. It doesn’t show the close succeeded, which is exactly the gap the suppression machinery exists to report.

The Unchecked Gap: Where the Theory Stops Helping

Everything the compiler can prove is about declared exceptions, and undeclared ones can still pass through

The compiler’s help has a boundary. Two rules from exception checking (JLS §11.2.3) show where. Catching a checked exception that the try body can never throw is a compile-time error. I confirmed it:

error: exception Checked is never thrown in body of corresponding try statement

And a catch for a class already covered by an earlier catch is rejected too:

error: exception Sub has already been caught

But catching an unchecked exception that the body never throws compiles and runs without complaint. I confirmed that as well. The compiler’s analysis simply doesn’t look at RuntimeException subclasses.

That is the Day 11 version of this series’ recurring “quiet failure.” DataCorruptionException was handled in the lesson only because someone chose to write catch (DataCorruptionException e). Nothing required it. Hejlsberg's scalability worry is the other side of the same coin: checked exceptions are loud and sometimes too loud, while unchecked ones are silent unless a human adds a handler on purpose.

Why These Concepts Matter

Exceptions look like one feature, but the lesson combines four independent design decisions, each with a named origin. Taking failure out of the return value is Goodenough’s problem (1975). Terminating instead of resuming is the same choice CLU made (Liskov and Snyder, 1979). Declaring exceptions in signatures is an idea CLU also had, and Hejlsberg’s 2003 critique is the best-known argument against Java’s version of it. And scope-bound cleanup is Stroustrup’s RAII, rebuilt for a garbage-collected language as nested handlers.

The most useful habit this lesson builds is reading the compiler’s output instead of trusting a mental model. The close order, the copied finally body, and the rethrow into an outer catch are all visible in a few dozen lines of javap output, and that evidence is stronger than a description of how things "should" work.

The Arbiter Journey Continues

One concept at a time, this series is building toward Arbiter, a microservices-based test management platform using Java, Spring Boot, databases, testing frameworks, Docker, and AWS. The theory above will matter there in a concrete way: every database connection, statement, and file handle in a test-run service is an AutoCloseable, so the nested-handler behavior from today is what keeps a failed run from leaking them. And Arbiter's own domain failures, like an invalid test-case status, will need a deliberate choice between checked and unchecked, with Hejlsberg's versioning argument as a cost to weigh.

Follow along with the complete Arbiter playlist

https://youtube.com/playlist?list=PLZG2gr4IjsZM&si=StFLpldNdIOjc3ub

GitHub Repository

You can follow the complete learning journey, source code, explanations, and future lessons here:

GitHub Repository: https://github.com/Someone-anon-coder/Arbiter

Follow the Complete Arbiter Series

Every Guide and Guide Theory article in this series, collected in one place:

Arbiter Guide: https://computer-info-1.medium.com/list/arbiter-java-20daa21849c8

Arbiter Guide Theory: https://computer-info-1.medium.com/list/arbiter-java-theory-13ecf0e21149

Explore My Other Learning Series

If you’re interested in my other programming and technology learning journeys, you may also enjoy:

Cybersecurity: https://computer-info-1.medium.com/list/cybersecurity-cba13dd0be16

Python Guide: https://computer-info-1.medium.com/list/python-guide-8e0b3bcab940

Python Guide Theory: https://computer-info-1.medium.com/list/python-guide-theory-81528784ebfe

GoLang Guide: https://computer-info-1.medium.com/list/golang-guide-e70e25ca8b42

GoLang Guide Theory: https://computer-info-1.medium.com/list/golang-guide-theoretical-082d8e7624ab

Matplotlib: https://computer-info-1.medium.com/list/my-progress-matplotlib-669052e8da38

What’s Next?

In Day 12, we pick Sets back up: HashSet and TreeSet, why a Set is really a Map wearing a disguise, and how to choose the right collection for a problem on purpose rather than by habit.

Happy coding! ☕

Companion Guide article: For the practical, code-driven walkthrough of this lesson, see the Day 11 Guide piece, published alongside this one. For the previous lesson’s theory, see Day 10 Guide Theory.

Understanding Java Exceptions — The Theory Behind Termination, Checked Exceptions, and Cleanup the… was originally published in CodeX on Medium, where people are continuing the conversation by highlighting and responding to this story.

Scan a QR holding 2NAOXV31B*LJLQIZLVLYD2$M39DERQ91EFD4/32P9IKP at the passphrase prompt of Krux 25.10.0, running under CPython, and those 44 characters come back as your passphrase. They’re the base43 text of an encrypted QR code, and the right key for it had just been typed in. Krux decrypted it, then threw the result away and kept the ciphertext.

Krux is open-source firmware that turns cheap K210 boards into Bitcoin signing devices. Since 25.09.0 it can decrypt its own encryption envelope, KEF, in most of the places it takes data in, including the menu item that scans a BIP-39 passphrase from a QR. The 25.10.1 changelog has the bug in one line: “Krux encrypted mnemonic as a passphrase is invalid, but no error was raised.” It says the base43 envelope was shown and used as the passphrase, deriving the wrong wallet.

Yesterday I wrote about what Krux does with a non-ASCII passphrase from a QR. This is the bug that put an ASCII check on that path in the first place.

One except clause, two meanings

The scan handler runs decrypt_kef(…).decode() inside a try with two except branches. KeyError means the key was wrong, and it shows Failed to decrypt. ValueError carries the comment “not KEF or declined to decrypt” and does nothing, so the scanned text falls through and becomes the passphrase. For a QR that holds a plain passphrase, that’s exactly right.

The trouble is the .decode(). A Krux encrypted mnemonic holds the entropy as raw bytes rather than the words. The PR that fixed it says what the user actually wanted was the mnemonic as a lowercase, space-separated string. Raw entropy almost never decodes as UTF-8. I tried a million random 16-byte values, the size behind 12 words, and 90 decoded. For 32 bytes, 24 words, none did. And in CPython the error that raises, UnicodeDecodeError, is a subclass of ValueError. So the decode failure landed in the not-KEF branch.

The board didn’t behave the same way. According to the PR, MaixPy raised a TypeError there instead, which neither branch catches, with the message Can’t convert ’int’ object to str implicitely. Krux’s menu catches anything that escapes an item and prints Error: followed by the exception, so on a device the scan should have ended on an error screen. The changelog’s wording, no error and the wrong wallet, matches the simulator.

What I ran

I exported the 25.10.1 tree, which carries the tests that came with the fix, and ran tests/pages/test_wallet_settings.py: 17 passed. Then I put back the 25.10.0 version of wallet_settings.py and ran it again: 3 failed, 14 passed. One of the three is the case itself, an envelope from the test file that wraps a single 0x8f byte under the key “a”. The fixed code returns to the menu with Failed to load. The old code returned the envelope.

The test feeds the envelope in as bytes, so I fed the same envelope in as base43 text, the way a QR carries it, and took it on to the fingerprint. The old code handed back the 44-character string with nothing flashed on screen. On the test suite’s 12-word mnemonic that passphrase opens wallet 974aa24d. The same words with no passphrase open 55f8fc5d. Both are valid wallets.

The confirmation screen wasn’t hiding anything, to be fair to it. It showed the fingerprint, Passphrase (44): and the string itself above Proceed?. Someone expecting twelve lowercase words would see base43 and stop, unless they’d long since stopped reading that screen.

Forty-five days, and a fix that was later softened

KEF decryption reached the passphrase scanner in commit ccb65290 on 23 May 2025 and first shipped in 25.09.0 on 15 September. tadeubas found the bug, jdlcdl’s PR #756 was opened and merged on 29 October, and 25.10.1 went out on 30 October. That’s 45 days in a release.

The fix decodes the decrypted bytes in a try of their own and fails with Failed to load. The wallet descriptor and address loaders had the identical line and got the same change. It also added a check that refused any passphrase with a byte over 126. In 26.03.0, five months later, that refusal became a warning you can click through, which is where yesterday’s piece picks it up.

If you write Python that also has to run on MicroPython, this is the pattern to grep for: an except ValueError meant for one failure, around a call that can also raise UnicodeDecodeError. On CPython it swallows the decode error. On this board it raised something else entirely, and the loud failure was the one on the device.

What I didn’t check

I didn’t run any of this on a K210. The device behaviour is the PR author’s account, who says it was built and tested on the simulator and an Amigo, read against Krux’s menu code. I don’t know how many people scanned an encrypted mnemonic at that prompt in those 45 days, and nothing public says.

Krux source read at tags v25.09.0, v25.10.0, v25.10.1 and v26.03.0, release dates from the GitHub API. Tests and the decode count run 8 October 2026 on CPython 3.13.6 with pytest 9.1.1.

Krux kept an encrypted QR’s own text as the passphrase, because UnicodeDecodeError is a ValueError was originally published in CodeX on Medium, where people are continuing the conversation by highlighting and responding to this story.