Installation
Outcome: Atomic is on yourPATH and atomic --version prints a version.
Prerequisites: A supported shell. See Prerequisites.
Install
Package managers
Install with npm:--ignore-scripts if you want to disable dependency lifecycle scripts during a package install.
Workflow persistence uses a local SQLite journal by default. No database server or separate database installation is needed. The default file is ~/.atomic/workflows/journal.sqlite; configure another location with ATOMIC_WORKFLOW_JOURNAL_PATH or the workflow storage settings. To share runs across machines, see Sharing storage across hosts.
Keep a standalone archive’s complete directory, including node_modules, libraries, and licenses. Package managers select the runtime for your platform automatically.
Release archive
Alternatively, install the self-contained release archive, which needs no Node.js or package manager. On macOS or Linux:SHA256SUMS, verifies the checksum, and keeps the complete payload in a versioned directory.
In an interactive terminal it prints the release and platform it is installing, draws a live progress bar with the percentage and megabytes downloaded, confirms each phase on one line, shows the Atomic logo (UTF-8 terminals on macOS/Linux, Windows Terminal on Windows), and ends with a To start: block. PATH guidance appears only when the launcher directory is not already on your PATH. When a different version is installed it prints Installed version: <tag> before upgrading.
Set NO_COLOR=1 for plain text instead: no colours, no progress bar, and no logo, with Downloading <archive> (<size> MB) ... done in place of the bar. The installer also switches to plain output on its own when standard output is not a terminal, when CI is set, or (on macOS/Linux) when TERM is dumb or unset. Plain mode changes only the presentation; verification, error messages, and exit codes stay the same.
On macOS or Linux, the default paths are ~/.local/share/atomic for versioned payloads and ~/.local/bin/atomic for the launcher. The installer never edits your shell configuration; when ~/.local/bin is not on your PATH it prints a paste-safe export PATH=... command (or fish_add_path for fish) and names the startup file to add it to.
On Windows, the defaults are %LOCALAPPDATA%\atomic for payloads and %LOCALAPPDATA%\atomic\bin\atomic.cmd for the launcher. The installer prints Installed to <path>, and when it adds the bin directory to your User PATH it says so and asks you to open a new terminal.
The installer accepts these environment variables:
ATOMIC_VERSION
Pin an exact release tag instead of the latest release, or pass a flag that overrides it. On macOS or Linux:MAJOR.MINOR.PATCH or MAJOR.MINOR.PATCH-alpha.REVISION release tag form and are honored literally: if GitHub answers with a different release tag, the installer stops before downloading anything rather than installing a version you did not ask for.
Rerunning the installer
If the release you ask for (or the latest release, when you pin nothing) is already installed and healthy, the installer printsatomic <tag> is already installed; skipping download (use --force to reinstall) and stops there. It still looks up the release tag and prints Installed to <path> and any PATH guidance, but it downloads nothing and leaves the installed files alone. On Windows it also adds the bin directory to your User PATH if it went missing.
An install counts as healthy when current points at that release’s version directory inside the install root (a current that points at a versions directory somewhere else is repaired) and the launcher resolves to it. On macOS/Linux that means the launcher link resolves to an executable current/atomic; the installer never runs the installed binary to decide. On Windows it means current\atomic.exe --version reports the release and the atomic.cmd shim and atomic-current junction match what the installer creates. On both platforms the version directory must still hold the files Atomic needs to start: package.json, app.js, native-modifiers.js, native-module-path.js, native-platform.js, and the builtin and node_modules directories. A different version, or a missing or broken launcher or payload, installs exactly as before and repairs the install.
To reinstall a healthy install anyway, pass --force on macOS/Linux or -Force on Windows, or set ATOMIC_FORCE_INSTALL=1. The environment variable works with curl ... | sh and irm ... | iex, where you cannot pass a flag:
ATOMIC_INSTALL_DIR
Override the install root that holds the versioned payloads (default~/.local/share/atomic on macOS/Linux, %LOCALAPPDATA%\atomic on Windows). On macOS/Linux, a relative value resolves against the physical directory where the installer starts and is used exactly as given, including any trailing whitespace or newline. The install root cannot equal or sit inside the launcher path (ATOMIC_BIN_DIR/atomic); impossible layouts fail before any download or filesystem change.
ATOMIC_BIN_DIR
Override the launcher directory (default~/.local/bin on macOS/Linux, %LOCALAPPDATA%\atomic\bin on Windows). Relative values resolve the same way as ATOMIC_INSTALL_DIR. It cannot sit inside the install root’s current or versions directories, which the installer replaces on every install. A Unix value containing : cannot be one PATH entry, so the installer prints direct-run guidance instead of editing PATH.
GITHUB_TOKEN / GH_TOKEN
Optional; raises GitHub API limits on shared networks. Curl and GNU Wget keep the token in a protected temporary file instead of process arguments. BusyBox Wget remains supported without a token, and with a token when the latest-release redirect avoids the API; if an authenticated API fallback is needed, install curl or GNU Wget rather than exposing the token.Which runtime runs your workflows
How you install Atomic decides which runtime hosts it: a package-manager install runs under Node, while the standalone binaries are Bun-compiled and run under Bun. Authored workflows execute inside whichever host is active, so a workflow that reaches for aBun.* global runs only under the standalone binary and fails with Bun is not defined under an npm install. Installing Bun separately does not change that — the npm install still runs on Node. Write workflow code against APIs both hosts provide, such as node:child_process and node:fs; see Custom Workflow Authoring for the rule and worked examples.
Alpine and musl Linux archives
The shell installer detects Alpine and selectsatomic-linux-x64-musl.tar.gz or atomic-linux-arm64-musl.tar.gz. Keep the complete archive, including payload-local libgcc and libstdc++; stock Alpine needs no runtime package install.
Clipboard setup depends on your environment:
- Clipboard: install
wl-clipboardon Wayland,xcliporxselon X11, or the Termux:API app andtermux-apipackage on Termux. OSC 52 forwards copies over SSH, Mosh, or Rex and is a fallback on headless Linux. SetATOMIC_CLIPBOARD_OSC52=1, or the legacyPI_CLIPBOARD_OSC52=1, to force terminal forwarding. Your terminal must support it; forwarding does not confirm a successful local clipboard write.
Uninstall
On macOS or Linux, for a default archive install, remove~/.local/share/atomic and the ~/.local/bin/atomic link.
On Windows, remove %LOCALAPPDATA%\atomic. If you set ATOMIC_BIN_DIR, also remove atomic.cmd and the atomic-current junction from that directory, then remove the directory from your User PATH.
For a package install, remove the global package with the same package manager. With npm:
~/.atomic/agent/ unless you delete that directory yourself.
Verify the install
Run:command not found, the launcher directory is not on your PATH yet. Open a new shell, or add the bin directory the installer printed to your PATH and try again.