Install¶

VPC Atlas comes in three distributions. All three include the dashboard (vpcatlas serve), so there is nothing extra to install for it, and all three run the same five commands. Pick the one that fits where you work.

Channel	Needs	Command line	Dashboard	Updates
Binary	Linux, macOS or Windows; nothing else	yes	yes	run the install script again
Python package	Python 3.12 or newer	yes	yes	`pipx upgrade vpcatlas`
Docker image	Docker	yes	yes	`docker pull vpcatlas/vpcatlas`
From source	Python 3.12 or newer, git	yes	yes	`git pull`

Binary¶

One file, with Python and every dependency inside it.

curl -fsSL https://vpcatlas.com/install.sh | sh
vpcatlas --version

What the script does¶

Detects the operating system (Linux or macOS) and the CPU (x86_64 or arm64).
Finds the latest release on GitHub, or the one you pin.
Downloads vpcatlas-<version>-<os>-<arch>.tar.gz and SHA256SUMS from the GitHub release of that version.
Compares the SHA-256 of the archive with SHA256SUMS. If they differ, it stops and installs nothing.
Copies the vpcatlas binary into place in two steps (copy, then rename), so a running copy is never replaced half-written.
Prints the install path and the version, and warns when the directory is not on your PATH.

It needs curl or wget, tar, mktemp and sha256sum or shasum, which Linux distributions and macOS already have. It never calls sudo: it installs into /usr/local/bin when you can write there and into ~/.local/bin otherwise.

Two environment variables control it:

Variable	Meaning	Default
`VPCATLAS_VERSION`	Version to install, for example `0.1.0` (a leading `v` is accepted).	The latest release.
`VPCATLAS_INSTALL_DIR`	Directory for the binary. It is created when missing.	`/usr/local/bin` when you can write to it, else `~/.local/bin`.

# A pinned version in a directory you own
curl -fsSL https://vpcatlas.com/install.sh | VPCATLAS_VERSION=0.1.0 VPCATLAS_INSTALL_DIR="$HOME/bin" sh

You can read the script before running it: https://vpcatlas.com/install.sh.

Manual download¶

Every release on the releases page carries one archive per platform and a SHA256SUMS file. The archive holds the vpcatlas binary (vpcatlas.exe on Windows) and the LICENSE.

Platform	Archive
Linux, Intel/AMD	`vpcatlas-<version>-linux-x86_64.tar.gz`
Linux, ARM	`vpcatlas-<version>-linux-arm64.tar.gz`
macOS, Intel	`vpcatlas-<version>-darwin-x86_64.tar.gz`
macOS, Apple silicon	`vpcatlas-<version>-darwin-arm64.tar.gz`
Windows, x86_64	`vpcatlas-<version>-windows-x86_64.tar.gz`

The install script covers Linux and macOS. On Windows download the archive by hand, or use the Python package or the Docker image.

Download, verify and install on Linux or macOS:

VERSION=0.1.0
NAME=vpcatlas-$VERSION-linux-x86_64        # or linux-arm64, darwin-x86_64, darwin-arm64
BASE=https://github.com/vpcatlas/vpcatlas/releases/download/v$VERSION

curl -fsSLO "$BASE/$NAME.tar.gz"
curl -fsSLO "$BASE/SHA256SUMS"

# Linux
grep " $NAME.tar.gz\$" SHA256SUMS | sha256sum -c -
# macOS
grep " $NAME.tar.gz\$" SHA256SUMS | shasum -a 256 -c -

tar -xzf "$NAME.tar.gz" vpcatlas
sudo install -m 755 vpcatlas /usr/local/bin/vpcatlas
vpcatlas --version

On Windows, in PowerShell:

$Version = "0.1.0"
$Name = "vpcatlas-$Version-windows-x86_64"
$Base = "https://github.com/vpcatlas/vpcatlas/releases/download/v$Version"
Invoke-WebRequest "$Base/$Name.tar.gz" -OutFile "$Name.tar.gz"
Invoke-WebRequest "$Base/SHA256SUMS" -OutFile SHA256SUMS

(Get-FileHash "$Name.tar.gz" -Algorithm SHA256).Hash.ToLower()
Select-String -Path SHA256SUMS -Pattern "$Name.tar.gz"      # the two hashes must match

tar -xzf "$Name.tar.gz" vpcatlas.exe
.\vpcatlas.exe --version

Move vpcatlas.exe to a folder on your PATH to run it from anywhere.

Upgrade and uninstall¶

To upgrade, run the install script again: it replaces the binary in place. Pin VPCATLAS_VERSION to move to a specific version or to go back.

To uninstall, delete the file:

rm "$(command -v vpcatlas)"

The binary keeps no state of its own. Output goes to the directory you choose with --output-dir (default ./vpcatlas-out), so there is nothing else to clean up.

Python package¶

Python 3.12 or newer. The dashboard is part of the package, not an extra.

pipx install git+https://github.com/vpcatlas/vpcatlas
vpcatlas --help

pipx puts the tool in its own virtual environment and the command on your PATH. Upgrade with pipx upgrade vpcatlas.

With plain pip, use a virtual environment:

python3.12 -m venv .venv
. .venv/bin/activate
pip install git+https://github.com/vpcatlas/vpcatlas
vpcatlas --version

The package also runs as a module, which is handy when the vpcatlas script is not on the PATH:

python -m vpcatlas --help
python -m vpcatlas discover --profile audit

Docker¶

The image is vpcatlas/vpcatlas on Docker Hub, for linux/amd64 and linux/arm64. Tags are the version (0.1.0), the minor line (0.1) and latest.

docker pull vpcatlas/vpcatlas
docker run --rm vpcatlas/vpcatlas --version

The entrypoint is vpcatlas, so whatever follows the image name is a vpcatlas command. With no command, the image serves the dashboard on port 8080 (serve --host 0.0.0.0 --port 8080). The process runs as an unprivileged user (atlas, uid 10001) with /home/atlas as its home.

Run a command¶

Mount your AWS configuration read-only and a folder for the output:

docker run --rm \
  -v "$HOME/.aws:/home/atlas/.aws:ro" \
  -v "$PWD/vpcatlas-out:/data" \
  vpcatlas/vpcatlas discover --profile audit --regions eu-west-1 --output-dir /data

On Linux the container user (uid 10001) usually cannot read your ~/.aws or write to your folder. Run it as yourself and keep the home directory the image expects:

docker run --rm --user "$(id -u):$(id -g)" -e HOME=/home/atlas \
  -v "$HOME/.aws:/home/atlas/.aws:ro" \
  -v "$PWD/vpcatlas-out:/data" \
  vpcatlas/vpcatlas discover --profile audit --regions eu-west-1 --output-dir /data

Serve the dashboard¶

docker run --rm -p 127.0.0.1:8080:8080 \
  -v "$HOME/.aws:/home/atlas/.aws:ro" \
  vpcatlas/vpcatlas serve --host 0.0.0.0 --profile audit

Open http://127.0.0.1:8080. The 127.0.0.1: in -p keeps the port off your network; the dashboard shows your network topology, so publish it wider only behind authentication (see VPCATLAS_AUTH_PASSWORD in Configuration). The image sets VPCATLAS_REFRESH_SECONDS=0, which means one scan at start and manual refreshes afterwards; set the variable to rescan periodically:

docker run --rm -p 127.0.0.1:8080:8080 -e VPCATLAS_REFRESH_SECONDS=900 \
  -v "$HOME/.aws:/home/atlas/.aws:ro" \
  vpcatlas/vpcatlas serve --host 0.0.0.0 --profile audit

To show a scan you already made, without calling AWS, mount the folder and pass the graph file:

docker run --rm -p 127.0.0.1:8080:8080 -v "$PWD/vpcatlas-out:/data:ro" \
  vpcatlas/vpcatlas serve --host 0.0.0.0 --cache /data/vpcatlas-graph.json

Credentials in the container¶

Three ways, from most to least convenient:

Mount ~/.aws as in the examples above, and select the profile with --profile or -e AWS_PROFILE=audit.
Pass environment variables by name only, so the values come from your shell and never appear in the command line: -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AWS_SESSION_TOKEN.
Run it on AWS (ECS, EKS, EC2, Lambda) and let the role of the workload provide the credentials.

A credential_process profile does not work inside the image, because its helper binary is not in it. An SSO profile (sso_* keys) does: the AWS libraries resolve it from the token cache under the mounted ~/.aws, until that token expires (the read-only mount stops a refreshed token from being written back). For a long run, resolve the profile on the host and pass the short-lived keys:

eval "$(aws configure export-credentials --profile audit --format env)"
docker run --rm -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AWS_SESSION_TOKEN \
  -v "$PWD/out:/out" vpcatlas/vpcatlas discover --regions eu-west-1 --output-dir /out

From source¶

git clone https://github.com/vpcatlas/vpcatlas.git
cd vpcatlas

# with uv
uv venv --python 3.12
uv pip install -e ".[dev]"

# or with pip
python3.12 -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"

vpcatlas --version

The dev extra adds the test and lint tools. make binary builds the one-file binary and make docker-build builds the image from deploy/Dockerfile. See Contributing.

What each channel includes¶

	Binary	Python package	Docker image	From source
`discover`, `inventory`, `diagram`, `iam-policy`	yes	yes	yes	yes
`serve` (dashboard)	yes	yes	yes	yes
Diagrams in draw.io and Lucid format	yes	yes	yes	yes
Auditor policy (`vpcatlas iam-policy`)	yes	yes	yes	yes
Needs Python on the machine	no	yes	no	yes
Reads `~/.aws` and the standard credential chain	yes	yes	with a mount	yes
SSO profiles	yes	yes	from the mounted cache while the token is valid	yes
`credential_process` profiles	yes	yes	no, pass keys	yes
Runs as a service (ECS, Kubernetes, Lambda)	no	no	yes	no

Next: the Quickstart.