Using Atlas

Install

You need Docker with Compose 2.24 or newer, and git.

git clone https://github.com/outset-systems/atlas.git && cd atlas
printf 'ATLAS_ADMIN_PASSWORD=%s\n' "$(openssl rand -base64 24)" > .env
docker compose -f compose.public.yaml up -d

Open http://localhost:5006 and sign in as admin with the password in .env. To look around an invented demo lab first, add ATLAS_FALLBACK=bundled to .env and run the last command again. The install guide covers TLS and reverse proxies.

Your first map

A new Atlas opens with an invitation, This atlas is uncharted. Guided setup has four steps:

1. Name your atlas.
2. Start from a scan you ran yourself, your router's leases, a device list or by hand.
3. Networks. Check the networks it found, or add one.
4. Devices. Pick which devices to add.

You can come back to it from Settings → Edit the map → Guided setup.

Importing devices

nmap

nmap -sn -oX - 192.0.2.0/24

Running it with sudo adds the makers of devices, which helps Atlas suggest a type for each one to check.

Router leases

Paste a lease file from ISC DHCP, dnsmasq, Kea or Windows Server (Get-DhcpServerv4Lease). The format is detected, and expired leases are skipped.

CSV

name,ip,kind,zone,role,url,url_label,notes

Only name is required. Kinds are physical, vm, network and unknown.

The views

The band along the top holds the views. Hover Atlas on a desktop for the sky, the depths and the tripwire watch.

Admins also get Accounts. The end of the band holds the light or dark switch, Settings and the Index of places and services.

What the colours mean

Atlas polls every 30 seconds, and the worst monitor on a place wins. If one source goes quiet, only its colours disappear. If they all do, the footer reads the watch is silent. Settings → Source status shows which source is which.

Connecting monitoring

Admins set this up under Settings → Data sources: add the address and key, press Test, then Save.

• Uptime Kuma colours the markers. Name each monitor after the place's id, so Atlas can match them.
• Prometheus supplies the numbers, not the colours.
• Loki supplies charts.

To let an AI tool read the map, use Settings → Connections → Let a tool read this map. The token shows once. The connection is read-only, and places hidden behind a group are never included.

Tripwires

Chart your honeypots and canary tokens, and Atlas lights the one that is touched. Reports come in through one signed webhook, which OpenCanary, Canarytokens or any script can call. It is off until an admin turns it on with ATLAS_TRIPWIRES_WEBHOOK=1 and a secret, then follows Tripwires → Set up. Only admins see where bait sits. Atlas never plants any.

Maps and regions

• Map style sets the background and tilt for your browser only.
• Admins can upload a map image (PNG, JPEG, GIF or WEBP up to 24 MB) or build a map from an address, which asks OpenStreetMap for the data.
• Regions are detailed maps of a room or rack. They can open as you zoom in, nest inside each other and be linked directly with #region=<id>.

Accounts and hidden places

• The default mode is real sign-in with local accounts. Require TOTP with ATLAS_MFA_REQUIRED set to admins or all.
• Directory sign-in is LDAPS only, and Save needs a passing Test first.
• Set Requires group on a place to hide it from people outside that group. Admins see everything.

Changes appear in the Chronicle of Changes, where Undo to here steps back through the last 50. Moving a place and rack layout changes are not in that list.

Keyboard

Atlas words

Atlas talks like a map. A few words to know:

Backups and upgrades

Stop the app, archive the volume, start it again. Keep secrets/master.key somewhere safe with the backup.

docker compose -f compose.public.yaml stop
docker run --rm -v atlas_atlas-data:/data:ro -v "$PWD":/backup alpine \
  tar czf /backup/atlas-backup-$(date +%Y%m%d).tar.gz -C /data .
docker compose -f compose.public.yaml start

Restoring is in the install guide. To upgrade:

git pull
docker compose -f compose.public.yaml up -d --build

Questions

Does it scan my network?

No. It reads what you paste in. Setup offers a command for you to run. The only exception is an optional relay you would install yourself.

Does it phone home?

There is no telemetry. It looks up whois data for public addresses unless you set ATLAS_WHOIS=0, and it calls OpenStreetMap if you build a map from an address.

Why does sign-in loop over http?

The sign-in cookie is Secure, so browsers keep it only on http://localhost or over TLS. Sessions also end after 60 idle minutes or 12 hours.

Why can't I reach it from another machine?

By default it listens on this machine only. Use an SSH tunnel (ssh -L 5006:127.0.0.1:5006 you@your-server) or a reverse proxy with TLS.

Why is a marker the normal colour when the host is off?

Healthy and no signal look the same. Check that a monitor is matched to that place.

Port 5006 is in use. What now?

Set ATLAS_PUBLISH=127.0.0.1:5007 in .env, or any free port, then run up -d again.

The admin account was not created. Why?

The password must be 12 characters or more. The app still starts, and its logs say why. Fix .env and run up -d again.