Environments: why it works on your machine and breaks online

Engineers have a sentence for this moment, and it may be the oldest in software: "it works on my machine." Said with a small shrug, usually a little defensive, it means, I ran this where I ran it and it worked, and whatever is happening where you ran it is a problem I cannot see from here. This chapter explains why the sentence exists, because the answer turns a family of confusing moments into one question you know how to ask.

An environment is the setup around the code

An environment is the specific setup where a piece of code runs.

The same code in two different setups can behave like two different products, because the setup includes everything around the instructions.

• The operating system underneath (macOS, Windows, Linux).
• The version of every installed tool; code written for a newer version of a language can fail on an older one.
• The configuration the code reads when it starts: which database to talk to, which keys to use, whether emails really send or are only logged.
• The data it finds there, friendly sample records in one place and real users' real information in another.
• Whatever memory, processing power, and neighboring software the machine happens to have.

"It works on my machine" rarely means the other machine is broken. It means the two environments differ in a detail nobody has found yet: a library that happened to be on your laptop from some other project, or a configuration value that exists in one place and not the other. The code held still while the setup around it changed.

The three environments most teams run

Because these differences ambush everyone eventually, teams standardized the places code runs.

• Development is your own machine, a sandbox where breaking things is cheap and expected, and nobody else can see in.
• Preview, which many teams call staging, is a private copy set up to match production closely, where a change auditions before anyone outside the team meets it.
• Production is the real thing, the version your users touch, where breakage costs trust and sometimes money.

What separates them is the list above: configuration, versions, and above all data, sample records in one and real customers in the other. When an AI tool asks whether a change should go to staging or production, this is the distinction it is checking. Deploy, a word you will now meet everywhere, means taking code from one environment and running it in another, almost always one step closer to users; hosting, renting a computer on the internet covers the machinery of the move.

How a change moves up to production

A change starts on your machine, where it can fail with no audience. When it works there, it moves to preview, where realistic configuration and data expose problems your laptop could never reveal, and only then does it reach production. At each step you ask the same question: did the change work in the environment just behind it, because if the answer is no, it does not move forward. Each stop catches what the previous one cannot: your laptop catches obvious breakage, preview catches the works-on-my-machine failures, and whatever slips past both is found by real users in production, which is why you want the first two stops to leave as little as possible.

What happens when a change skips the gates

On July 19, 2024, the security company CrowdStrike shipped a faulty content update for software that runs deep inside Windows machines. Roughly 8.5 million of those machines crashed worldwide, grounding flights and halting payment systems.

The post-incident reviews centered on the discipline this chapter has been describing: ship a change to a small group of machines first, watch how it behaves, then widen in stages. The same staged approach keeps working inside production too, because you can send a change to a few users there before you send it to everyone. Watching that first group is a monitoring job, and monitoring, how you know it broke (and what it costs) returns to it.

Your build will not ground flights, but the lesson transfers. The cost of a bad change scales with how many people meet it, and environments, moved through in order, control that number.

This site ran on a laptop while we wrote it

While this chapter was being written, the site you are reading ran as a development environment and nowhere else: one laptop, a dev server started with npm run dev, answering at an address that begins with http://localhost. Localhost is the name every computer uses for itself, so that address was reachable from exactly one machine on earth. Edits appeared seconds after saving, broken layouts and half-written paragraphs included.

The copy in front of you is the production version, the one that later made the trip through the gates. We point this out because environment diagrams can make the discipline look like enterprise machinery. The moment you run a dev server you own two environments, a private one where you can break anything and a public one where you cannot, and moving changes between them deliberately works at every scale.

What you can now do

This chapter closes the map, so take stock of what you can now do. You can decode the technical questions that stop you and split any product into the three parts from what software actually is. You can place each part on the map of where software lives and narrate the journey of a request. You can read a project's manifest, the file listing what it is built with, approve a pick of languages and frameworks, and make a save point with Git, the undo that makes AI edits safe, before a tool touches your files. As of this chapter, you can ask the question that settles every works-on-my-machine argument, which environment are we talking about.

Try it now

No setup: Pick any product you use and find where it admits to changing: search its name plus "changelog", "release notes", or "status"; most sizable products publish at least one of these pages. Read a few entries with this chapter in mind: every changelog line is a change that started on one person's machine and traveled the whole path to reach you, and status-page incidents are often the ones where an environment difference won.

With your tools: Open any project folder with Claude Code and ask it to start the dev server. For most JavaScript web projects the command is npm run dev, and the terminal prints a local address beginning with http://localhost. Open it in your browser: you are looking at your own private environment, the leftmost box in the diagram above. Turn off your Wi-Fi and the page still answers, because the request never touches the internet; the whole round trip runs inside one machine. If your laptop has none of these tools yet, the Setup Clinic takes you from bare machine to working toolkit. In Codex or Cursor the move is the same: open the project, ask the sidebar to run the dev server, and visit the localhost address it reports.

Chapter Summary

• An environment is the specific setup where a piece of code runs.
• The setup includes the operating system, tool versions, configuration, data, and the machine's resources, so the same code can behave differently from one environment to the next.
• Most teams run three: development on your own machine, preview as a private copy that matches production, and production where real users are.
• The biggest difference between them is the data: sample records in development and preview, real customer information in production.
• "Deploy" means taking code from one environment and running it in another, almost always one step closer to users.
• A change moves from development to preview to production, and at each step you only let it move forward once it has worked in the environment behind it.
• The cost of a bad change grows with how many people see it, which is why a wide change should move slowly and in stages, the lesson the industry relearned in the July 2024 outage.
• When a tool says a change is "tested," ask where it ran before you trust it.
• The moment you run a dev server you already own two environments, a private one and a public one, so this discipline works at every scale.
• Next, the level turns to the layers every product stands on, starting with Frontend, what users see.

Sources

• CrowdStrike post-incident review and remediation reporting (2024).
• Public news reporting on the July 19, 2024 global IT outage (2024).