Testing localhost

Why you need it

A browser tab cannot read a folder on your disk, and a page served over https:// is not allowed to open a connection to http://localhost. Both rules are deliberate — otherwise any website you visited could read your files and scan the services on your machine.

They protect you, and they are not something Atlas can work around from inside the page. So instead there is a small program you run yourself, on your side of that line. It does two things:

• Reads your project. Point it at a folder and it finds every endpoint, what each one expects, and which tables it touches.
• Forwards requests. So Send works against the server running on your own machine.

Install Atlas

Atlas installs from the browser — there is no download and no installer. Open it, then use your browser's install action:

• Chrome and Edge — an install icon appears at the right of the address bar. Or menu → Cast, save and share → Install page as app.
• Safari — File → Add to Dock.
• Firefox — no install, but everything on this page still works in a normal tab.

Installed, it opens in its own window with no address bar, keeps working offline, and keeps its data between sessions like any other app.

You can skip this entirely. A normal browser tab and the agent work exactly the same — installing only changes how it looks and launches.

Run the agent

In a terminal, from anywhere:

npx github:softtunners/atlas.api

It needs Node 18 or newer and installs nothing permanently — the command fetches it, runs it, and leaves nothing behind when you stop it. The source is here and it is short enough to read before you run it.

It prints something like this:

Atlas agent · 127.0.0.1:4400

Paste this into Atlas (it asks on the first local request):

  ws://127.0.0.1:4400?token=8fJ2n...

Leave it running while you work, and stop it with Ctrl+C when you are done.

Connect them

Send a request to a local address and Atlas asks for this line — paste it in and the request you were sending carries on. Nothing to set up in advance.

If you would rather do it ahead of time, it is under Settings → Local agent. Either way a marker appears in the top bar while the agent is answering.

The token changes every time you start the agent, so paste the current one. That is deliberate — see below.

Using it

To scan a project, choose Select project folder on the projects screen, then browse to it or paste its path. The scan runs on your machine and the workspace opens on the endpoints it found.

To send requests, nothing about the workspace changes. Anything pointing at a local address goes through the agent automatically:

• http://localhost:3000/api/users
• http://127.0.0.1:8080, and any port
• containers, and other machines on your network or VPN

Public URLs carry on going straight out, agent or not. Set {{baseUrl}} to your local server in an environment and every request in the collection follows.

Is this safe?

It is a program listening on a port, so the question deserves a real answer rather than reassurance. Three things guard it, and all three apply to every connection:

• It binds 127.0.0.1 only. Nothing else on your network can see it — not another machine, not a device on your wifi.
• It reads only where you point it. A folder you choose, when a connected tab asks. It refuses system directories and your home folder itself.
• It checks which page is calling. Requests from any other site are refused before anything is read.
• It requires a token generated fresh each run and printed only in your terminal. Close the agent and it is gone.

It also refuses cloud metadata addresses outright — the ones that hand out credentials to anything on the machine that asks.

It is a few hundred lines with no dependencies, which is deliberate: everything a program like this depends on is something you are trusting too. Read it before you run it, and stop it with Ctrl+C when you are done.

When it will not connect

The indicator stays grey. Check the agent is still running, and that the token you pasted is from the current run rather than an earlier one.

Port already in use. Start it somewhere else with npx github:softtunners/atlas.api --port 4401 and paste the new URL.

Firefox or Safari. Both refuse connections from an https:// page to a local address, whatever the agent does. Chrome or Edge is the way round it today.

Requests still fail. If the agent is connected but a request does not land, the message comes from your machine rather than from us — “nothing is listening on localhost:3000” usually means the server is not running.

Still stuck? Open an issue with what the agent printed. Back to the docs.