Getting started¶
Requirements¶
An account on atomgpt.org, and Python 3.10 or newer.
Atomsh is tested on Linux and on Windows through WSL2. macOS is expected to work, since the installer avoids GNU-only tools and the code uses nothing Linux-specific, but it has not been run there yet; reports welcome. Native Windows is not supported, because the installer is a shell script and the terminal handling assumes a POSIX tty.
You do not need an OpenAI or Anthropic key. Atomsh talks only to atomgpt.org.
Install¶
The installer prefers uv, falls back to a
virtualenv, and bootstraps uv if the system Python has no working pip. It
installs into an isolated environment and links a launcher into
~/.local/bin. No sudo, nothing system-wide.
If you already use uv or pipx, install it directly from PyPI:
Both work anywhere Python does, including macOS, and skip the shell installer entirely.
If ~/.local/bin is not already on your PATH, the installer adds it to your
shell startup file and prints the one-line export to apply it to the shell
you are in, so you do not have to open a new terminal. Set
ATOMSH_NO_MODIFY_PATH=1 to be told rather than helped.
Connect¶
This opens atomgpt.org in your browser and starts a single-request listener on
127.0.0.1 at a random port. You approve once, the authorization code comes
back to that listener, and Atomsh exchanges it for a credential stored with
mode 0600 in ~/.config/atomsh/auth.json.
The loopback address is the point: the code travels from your browser to your
own machine and never crosses the network. The code_challenge in the URL is
PKCE, which stops an intercepted code from being redeemed by anyone else.
On a remote machine¶
Over SSH or on a cluster login node the browser runs on a different computer,
so the redirect lands on its 127.0.0.1, not on the host running Atomsh.
Nothing can arrive at the listener, because the listener is somewhere else.
atomsh login handles this without a flag. It waits for the redirect and
accepts a pasted address at the same time, whichever comes first. Approve in a
browser anywhere, let the 127.0.0.1 page fail to load, and paste its full
address into the terminal. The code is in it.
Locally there is nothing to do: the listener catches the redirect and the prompt disappears by itself.
atomsh login --manual skips the listener entirely, which is rarely needed.
If you would rather not use a browser at all:
Paste an API key from atomgpt.org under Settings, Account, API Keys.
To check or clear the stored credential:
First run¶
Start in a repository you do not mind it reading:
--readonly refuses every write and shell command, so it is a free look at
whether the answers are useful before letting it touch anything. Then drop the
flag; it will ask before each write or command.
Upgrading¶
Re-running the installer is the one instruction that works everywhere. It finds the existing install and upgrades it in place, whether that was a uv tool environment or the virtualenv fallback:
If you installed with uv or pipx directly, use those instead:
Check what you got with atomsh --version.
To run an unreleased commit, point the installer at the repository: