Skip to main content

Installing Atomic

This guide will help you install Atomic on your system. The recommended installation path is the hosted installer script from Atomic Storage. Development builds can still be installed from source.

Installation Methods​

Install the latest Atomic CLI release with the installer hosted by Atomic Storage:

curl -sSf https://atomic.storage/install.sh | sh

Install a specific version:

curl -sSf https://atomic.storage/install.sh | ATOMIC_VERSION=0.5.1 sh

Install to a user-writable directory:

curl -sSf https://atomic.storage/install.sh | ATOMIC_INSTALL="$HOME/.local/bin" sh

The installer detects your platform, downloads the matching GitHub release archive, verifies checksums when available, and installs the atomic binary.

Verify Installation​

atomic --version

Connect to Atomic Storage (optional)​

To create or clone hosted projects, first create an Ed25519 identity and register it with your Atomic Storage server. Registration creates your personal organization on the server and stores the server URL and default organization in your global Atomic configuration.

atomic identity new alice-acme --email alice@acme.com --set-default
atomic identity register https://atomic.storage
atomic org show

To create a hosted project for your team, select an organization, then create a workspace and project:

atomic org create acme --email dev@acme.com
atomic org set acme

atomic workspace create platform --visibility private
atomic workspace set platform
atomic project create api --kind rust

Organizations contain members and teams, workspaces group projects, and projects map to hosted Atomic repositories. For access rules and team management, see Team Collaboration.

Enable Shell Completions (optional)​

Turn on tab-completion for subcommands, flags, and live values like view names and change hashes. For zsh, add this to your ~/.zshrc:

source <(COMPLETE=zsh atomic)

See Shell Completions for other shells, the static atomic completions <shell> script, and troubleshooting.

Source Install (Development)​

Use a source install when you need to test unreleased changes.

1. Install Rust​

If you don't have Rust installed, download and install rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Choose the stable toolchain as your default:

rustup default stable

If you already have rustup installed, make sure to update it:

rustup update

2. Install System Dependencies​

Install the required libraries and header files for your operating system:

On Debian/Ubuntu:

sudo apt update
sudo apt install make libsodium-dev libclang-dev pkg-config \
                 libssl-dev libxxhash-dev libzstd-dev clang

On macOS:

brew install llvm libsodium openssl xxhash zstd

On Arch Linux:

sudo pacman -S clang libsodium gcc-libs rustup pkgconf \
               diffutils make xxhash zstd

On openSUSE Tumbleweed:

sudo zypper in clang-devel libopenssl-devel libsodium-devel \
               libzstd-devel pkgconfig xxhash-devel

On Fedora:

sudo dnf install clang-devel openssl-devel libsodium-devel \
                 libzstd-devel pkgconfig xxhash-devel

On Void Linux:

sudo xbps-install libgcc-devel libressl-devel libsodium-devel \
                  libzstd-devel xxHash-devel

3. Build and Install Atomic​

Clone the repository and install the CLI crate:

git clone https://github.com/atomicdotdev/atomic.git
cd atomic
cargo install --path atomic-cli

4. Add to PATH (if needed)​

If the atomic command is not found, you may need to add Cargo's bin directory or your chosen installer directory to your PATH.

On Linux/macOS, add to your ~/.bashrc, ~/.zshrc, or equivalent:

export PATH="$PATH:$HOME/.cargo/bin"

On Linux with systemd, you can also add to ~/.config/environment.d/envvars.conf:

PATH=$PATH:$HOME/.cargo/bin

Then reload your shell configuration:

source ~/.bashrc  # or source ~/.zshrc

Distribution Packages​

COMING SOON

Building from Git (Development)​

To build the latest development version:

git clone https://github.com/atomicdotdev/atomic.git
cd atomic
cargo build --release --all-features
cargo test
cargo install --path atomic-cli

Troubleshooting​

"Package not found" errors​

Make sure you've installed all required system dependencies for your platform. The build process requires development headers for several libraries.

Linker errors on macOS​

If you encounter linker errors on macOS, ensure you have the Xcode Command Line Tools installed:

xcode-select --install

You may also need to set the following environment variables:

export LIBRARY_PATH="$LIBRARY_PATH:$(brew --prefix)/lib"
export CPATH="$CPATH:$(brew --prefix)/include"

Permission denied errors​

If you get permission errors during installation, ensure your user has write access to the Cargo installation directory, or use sudo (not recommended) or install to a user-writable location.

Rust version too old​

Atomic requires Rust 1.70 or later. Update your Rust installation:

rustup update stable

Next Steps​

Now that Atomic is installed, create or clone your first repository. Then explore AI Agent Workflows, or learn the team collaboration model.

Uninstalling​

To remove Atomic installed by the hosted installer:

rm /usr/local/bin/atomic

If you installed to a custom ATOMIC_INSTALL directory, remove the binary from that directory instead.

To remove Atomic installed via Cargo:

cargo uninstall atomic-cli

Need help? open an issue on GitHub.