Lesson 1 of 7 · 5 min

Localhost is a route back to yourself

localhost, 127.0.0.1, and ::1 point to your own machine. When a browser opens http://localhost:3000, it is asking your Mac to connect to a process on your Mac.

What you'll learn

  • The mental model
  • Why there are three names
  • What localhost is not

localhost is not a website on the internet. It is a name your computer uses for itself.

When you open:

http://localhost:3000

your browser is not leaving your machine. It asks the operating system: “Is there a process on this computer listening on port 3000?”

If there is, you see the app. If there is not, you get a failure like “connection refused,” “site cannot be reached,” or “unable to connect.”

The mental model

Think of your Mac as a building.

  • localhost is the building you are already inside.
  • 127.0.0.1 is the IPv4 address for that same building.
  • ::1 is the IPv6 address for that same building.
  • 3000, 8000, or 11434 are doors inside the building.
  • A running process must be waiting behind the door.

So this:

http://localhost:3000

means:

Browser, ask this same machine whether something is waiting behind door 3000.

Why there are three names

You will often see these three values used almost interchangeably:

localhost
127.0.0.1
::1

They all mean “this machine,” but they are not identical in every situation.

127.0.0.1 is IPv4 loopback. ::1 is IPv6 loopback. localhost is a name that usually resolves to one or both of them.

Most of the time, you can use localhost and forget about the details. But when a tool behaves strangely, try the explicit address:

http://127.0.0.1:3000

That removes one layer of ambiguity.

What localhost is not

localhost does not mean “my website.”

It does not mean “my Wi-Fi address.”

It does not mean “something everyone can reach.”

When another person opens http://localhost:3000 on their machine, they are not connecting to your Mac. They are connecting to their own machine.

This is one of the most common beginner misunderstandings:

“It works on localhost. Why can’t my phone or teammate open it?”

Because their localhost points back to them, not to you.

Quick check

Start a tiny local web server:

mkdir -p /tmp/localhost-explorer-lab
cd /tmp/localhost-explorer-lab
echo "hello from my Mac" > index.html
python3 -m http.server 3000

Now open:

http://localhost:3000

Then try:

http://127.0.0.1:3000

Both should show the same file.

To stop the server, return to the terminal and press:

Control-C

What can go wrong

Nothing is listening

The browser reaches your Mac, but no process is waiting on the port.

Common messages:

Connection refused
ERR_CONNECTION_REFUSED
Could not connect to server

The fix is not to refresh harder. Start the app, or find the correct port.

The app is listening on a different port

Maybe your React app moved from 3000 to 3001. Maybe FastAPI is on 8000. Maybe Ollama is on 11434.

Use this command to see what is listening:

lsof -nP -iTCP -sTCP:LISTEN

IPv4 and IPv6 disagree

Occasionally, a process listens only on IPv4 or only on IPv6.

If localhost fails, try:

http://127.0.0.1:3000

If that works, the issue is probably address binding, not the app itself.