Installation¶

Atlantide is distributed two ways: as a standalone binary that bundles its own Python runtime, and as a package on PyPI.

	Standalone binary	PyPI package
Python needed	no	3.11 or newer
Providers available	the three built-in ones only	built-in and third-party plugins
Use it for	CI images, machines without Python, quick trials	anything using a provider plugin, or embedding the engine

The second row decides most cases. It is covered under provider plugins below.

---

Standalone binary¶

Every release publishes a binary for three platforms on the releases page. Each is a single executable of roughly 30 MB with no external dependencies.

Linux (x86-64)¶

curl -L -o atlantide \
  https://github.com/atlantide-org/atlantide/releases/latest/download/atlantide-linux-x86_64
chmod +x atlantide
sudo mv atlantide /usr/local/bin/

The binary is built on the current Ubuntu runner image and links against that image's glibc. On an older distribution, install from PyPI instead.

macOS (Apple silicon)¶

curl -L -o atlantide \
  https://github.com/atlantide-org/atlantide/releases/latest/download/atlantide-macos-arm64
chmod +x atlantide
xattr -d com.apple.quarantine atlantide
sudo mv atlantide /usr/local/bin/

Windows (x86-64)¶

curl.exe -L -o atlantide.exe `
  https://github.com/atlantide-org/atlantide/releases/latest/download/atlantide-windows-x86_64.exe

Move atlantide.exe to a directory on your PATH.

Confirm it runs¶

atlantide --version

atlantide 0.2.0

Provider plugins and the binary¶

Providers are discovered through the atlantide.providers entry-point group, which requires them to be installed alongside atlantide as Python distributions. A standalone binary has no site-packages for a plugin to be installed into, so it advertises no entry points and uses only the providers compiled into it:

$ atlantide providers
                                 3 provider(s)
┏━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ name   ┃ types ┃ module                     ┃ summary                        ┃
┡━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ aws    │    25 │ atlantide.providers.aws    │ AWS resources over boto3.      │
│ local  │     3 │ atlantide.providers.local  │ Files and no-ops on the local  │
│        │       │                            │ machine; needs no credentials. │
│ random │     4 │ atlantide.providers.random │ Values generated once at apply │
│        │       │                            │ and pinned in state.           │
└────────┴───────┴────────────────────────────┴────────────────────────────────┘

If a config imports a third-party provider, install from PyPI. The binary cannot load one, and the failure presents as config being unable to find the provider's types — which reads like a typo rather than a missing plugin.

---

From PyPI¶

Requires Python 3.11 or newer.

uv tool install atlantide     # standalone CLI, isolated environment
pipx install atlantide        # the same, via pipx

uv add atlantide              # into a project
pip install atlantide         # into the current environment

For the CLI alone, uv tool install or pipx are the better choices: both keep atlantide and its dependencies in their own environment rather than in the one you are working in.

Use uv add or pip install when embedding the engine as a library, or when a config imports a provider plugin — a plugin has to resolve in the same environment as atlantide itself.

Extras¶

The Postgres state backend needs an extra, because it pulls in a database driver most installations do not need:

pip install 'atlantide[postgres]'

The sqlite and S3 backends need nothing beyond the base install.

---

Building the binary yourself¶

Useful for a platform with no published asset, or to pin a binary to a commit of your own:

git clone https://github.com/atlantide-org/atlantide
cd atlantide
make binary          # uv run --extra build pyinstaller atlantide.spec --clean --noconfirm

The executable is written to dist/atlantide. A binary built this way bundles whatever is installed in the build environment, so this is also how to produce one that includes a provider plugin or the Postgres driver.

---

Verifying an installation¶

atlantide --version      # the version, and that the executable runs at all
atlantide providers      # which providers this installation can see

atlantide providers also lists any plugin that failed to load. That matters, because a plugin which does not load is otherwise invisible: config simply cannot find its types.

To confirm a working end-to-end setup without credentials or an AWS account, follow the walkthrough. It uses the local provider and creates only files on disk.

---

Upgrading and removing¶

uv tool upgrade atlantide     &&  uv tool uninstall atlantide
pipx upgrade atlantide        &&  pipx uninstall atlantide
pip install --upgrade atlantide  &&  pip uninstall atlantide

To upgrade a standalone binary, download the new release over the old file; atlantide --version confirms the replacement.

Upgrading does not touch state. If state is shared, note that a newer atlantide migrates the store forward automatically, while an older one refuses to read a newer store rather than misreading it. Upgrade every machine sharing a backend together — see Managing state.

---

Scaffolding a project¶

atlantide init writes a working project — atlantide.toml, a starter config and a .gitignore — and compiles the result before reporting success:

atlantide init                        # `minimal` template, local state
atlantide init --template aws         # an AWS starter instead
atlantide init --state s3 --bucket acme-atlantide-state \
               --key prod/atlantide.json --lock-table atlantide-locks

--template takes minimal or aws; --state takes local, s3 or postgres and writes the matching [state] table for you (--bucket, --key, --lock-table for s3; --dsn, --schema for postgres). --secrets selects keyfile, env or ssm. It refuses to overwrite existing files or to nest inside another project unless given --force.

The minimal template needs no credentials, which makes it the shortest path to seeing the engine skip an unchanged graph — see the quickstart.

---

Next steps¶

• How it works — the mental model, then a walkthrough that needs no AWS account.
• Building on AWS — a multi-environment stack built one resource at a time.
• CLI — every command and flag.