Atomic Agent

Atomic Agent: Install and first job

This page takes you from the download to one small, safe job on a test folder, on Windows 11 or on a Mac. It follows Pick it and plan, so read that page first if you have not chosen your model yet.

Install on Windows 11

The desktop app is the easy path. The docs call it "the recommended way to start if you don't live in a terminal," and it has the agent built in, so there is nothing else to install first.

1. Download the installer

Open the official download page:

https://atomicagent.io/download/

Pick the file for your PC:

The desktop app has its own version number, 0.0.8, and it comes with the v0.7.0 agent inside.

What you should see a downloaded file whose name starts with Atomic-Agent-Setup-0.0.8 and ends in .exe.

2. Run the installer

Open the file from your Downloads folder and follow the setup.

It installs for your account only, so it does not ask for administrator rights. The download page says the installer shows the publisher AtomicMail Systems OU.

What you should see the setup finishes, and Atomic Agent is in your Start menu. A desktop shortcut also appears.

3. Open Atomic Agent

Open Atomic Agent from the Start menu or the shortcut.

The first screen asks you to pick a model. Stop there and read "Turn on the safety switches first" below.

What you should see a screen asking you to choose a local model sized for your PC, or to add a cloud key.

If you would rather paste a command

You do not need this for the first hour, but you will need it later if you want Telegram, because the docs describe that setup in the terminal version.

Open PowerShell from the Start menu, but do not choose Run as administrator. Paste this and press Enter:

irm https://atomicagent.io/install.ps1 | iex

The installer checks the download before it installs anything. Then type this and press Enter:

atomic-agent --help

What you should see a list of commands. Then type atomic-agent and press Enter. A text screen opens and walks you through setup, where you choose a local model, a cloud provider, or your own server. The last setup step offers to bring in data from other AI agents, and you can skip it.

The terminal version and the desktop app can be installed side by side. They share the same settings folder, called .atomic-agent, in your home folder.

Install on a Mac

1. Check your Mac's chip

Open the Apple menu and choose About This Mac. A line that says Chip with an Apple M name means Apple Silicon, while a line that says Processor with Intel means Intel.

If your Mac is Intel, stop here. Atomic Agent's download page says the Mac files will not open on an Intel Mac, and the terminal version needs Apple Silicon too. The install page mentions building it yourself from the source code, which is not a beginner job, so go back to the main guide instead.

What you should see Chip with an Apple M name, and macOS 14 Sonoma or newer.

2. Download the app

Open the official download page:

https://atomicagent.io/download/

Download Atomic-Agent-0.0.8-arm64.dmg. The docs say it is signed and notarized, which means Apple has checked who made it.

What you should see a downloaded file named Atomic-Agent-0.0.8-arm64.dmg.

3. Drag it to Applications

Double-click the .dmg file, then drag Atomic Agent onto the Applications folder.

What you should see Atomic Agent in your Applications folder.

4. Open Atomic Agent

Open it from Applications or Launchpad.

The first screen asks you to pick a model. Stop there and read the next section.

What you should see a screen asking you to choose a local model sized for your Mac, or to add a cloud key.

If you would rather paste a command

As on Windows, you only need this later, for Telegram.

Open Terminal, which is in Applications inside the Utilities folder. Paste this and press Return:

curl -fsSL https://atomicagent.io/install | sh

Then type atomic-agent --help and press Return.

What you should see a list of commands. Then type atomic-agent and press Return, and a text screen opens to walk you through setup. You can skip the step that offers to bring in data from other AI agents.

Turn on the safety switches first

Do this whole section before you give Atomic Agent any job. The general checklist behind it is in the safety chapter.

1. Keep approval level 1

Level 1 is the default. The docs call it "paranoid," because every action that can change something asks first, so leave it there.

When the desktop app asks, it offers four answers: Allow once, Allow in this chat, Always allow, and Deny. For the first hour, use only Allow once and Deny. Allow in this chat stops asking about that kind of action until the chat ends, and Always allow saves a rule. Saved rules are listed in Settings › Privacy, where you can delete them.

If you use the terminal version, leave the mode on default and do not pick auto or bypass permissions. Never start it with --no-approval, which approves everything.

Some things are fenced even at higher levels. A few very dangerous commands, like ones that wipe a whole disk, are refused at every level. Others, like rm -rf (delete a folder and everything in it) and sudo (run as administrator), keep asking at every level below 5, and a yes for the rest of the chat never covers them.

This guide could not confirm a screen in the desktop app that shows or changes the approval level.

What you should see when the agent wants to change something, an approval card with Allow once and Deny.

2. Know what does not ask

Web search and reading web pages do not ask first, and the tools page says ordinary web browsing does not ask either. The approvals page also lists a prompt for a "site outside the allow-list," but this guide could not confirm when that one appears. Anything the agent sends to the web leaves your computer.

The docs disagree about raw web requests. The approvals page and the settings page say they run without asking by default, the tools page says they always ask, and the README says simple reads run without asking. The setting that controls this is http.approvalMode, and the choice always makes every request ask. This guide could not confirm a button for it in the desktop app.

In the browser, a few things do ask: clicking something that submits, posts, or deletes, and typing into a password, one-time code, or card field.

Browser control needs Chrome, Edge, or Chromium already on your computer, because Atomic Agent does not include a browser.

What you should see nothing to click here. Just know that web reading does not stop for a yes.

3. Make a new, empty folder

Make one new folder, for example atomic-tryout inside Documents, and put nothing personal in it. Copy in one harmless file, like a short note you typed yourself.

At level 1, reading a file outside the folder the agent works in asks first, and writing a file anywhere asks first. That helps, but it is not a wall, because a command you approve can reach any file your account can reach. So read every request.

What you should see one new folder with one harmless file in it.

4. No email, bank, or chat bot in the first hour

Stay logged out of email, your bank, and online stores in any browser the agent can open.

Do not set up Atomic Mail (the agent's own email inbox), Composio (a way to connect accounts like Gmail and Slack), Telegram, or Discord yet.

What you should see nothing connected in the app's integrations.

5. Set a spend limit at the provider

A free Gemini key with no card on file has no bill to cap.

If you use OpenRouter, a provider that sells many models through one key, give the key a credit limit when you create it. OpenRouter's own docs recommend a limit on every key, and they say a key with no limit lets a runaway agent spend your whole balance.

If you add a paid key from OpenAI or Anthropic, set a monthly limit on that company's website first. The screen names are in the safety chapter.

Atomic Agent has its own money settings too, like agent.task.maxCostUsd, but the docs say that spend is an estimate. Treat it as a speed bump, not a real cap.

What you should see either a free key with no card, or a limit saved at the paid company.

6. Optional: turn off usage reports

Atomic Agent sends anonymous usage stats and crash reports by default, though the security page says they never include your messages, file paths, or keys. To turn both off in the desktop app, use the Privacy switch in Settings.

What you should see the Privacy switch off, if you chose to turn it off.

Connect a model

1. Get a free Gemini key

Go to Google AI Studio and create an API key. You do not need a card.

Keep the key private, and do not paste it into the chat.

What you should see a long key you can copy.

2. Add it to Atomic Agent

In the desktop app, open Add provider, which is on the first-run screen in the Cloud models list. Later you can find it under Settings › Models › Cloud providers. Choose Gemini and paste your key where it asks.

In the terminal version, type /providers, add a provider, and choose Gemini.

After you add Gemini, the first three models in the list are marked Cheap, Balanced, and Best. This guide could not confirm which of those the free Gemini tier allows, so if you get an error about billing or limits, try another model in the list.

OpenRouter is added the same way, but set its credit limit first.

Your key is saved in a file on your computer, inside the .atomic-agent folder. The docs say keys are stored as plain text there, so treat that folder as private.

What you should see Gemini set up as your model, and a message box where you can type.

3. If you stay local instead

If you pick a local model, the app can start on the small starter model while it downloads a bigger model in the background and shows "Getting the best model for this computer." When it is done, it asks Switch now or Later, and chats keep working on the small model in the meantime.

Expect a local model on an 8 GB or 16 GB laptop to stall or loop on multi-step jobs.

What you should see a download bar above the message box, then a Switch now or Later choice.

Or use a local model

Atomic Agent's own local model, above, does not need Ollama. If you would rather use Ollama, install it and download a model first with Run a local model with Ollama.

In the desktop app, on the first-run screen click Already run Ollama or LM Studio? Use it instead (or the Cloud models card). Later, open Settings › Models › Cloud providers, click Add provider, and choose Ollama (local). There is no key screen; pick your model from the list. In the terminal version, add a provider and choose the same Ollama (local) preset, which fills in http://localhost:11434 and saves no key.

What you should see the models you downloaded in Ollama offered in the list, then a reply when you say hello.

Your first safe job

Tell the agent where your new folder is. On Windows 11, right-click the folder and choose Copy as path. On a Mac, right-click the folder, hold the Option key, and choose Copy as Pathname. Paste that into your message.

You can type:

Work only in this folder: (paste the folder path here). Read the one file in it. Then write a new short note in the same folder that sums it up. Do not touch any other folder.

When an approval card shows up, read what it wants to do before you click.

If a finished answer shows a line like Auto-approved 3 actions, click it to see a list of what ran without asking, and why.

When it is done, open the folder yourself.

What you should see your original file, plus one new note. Nothing else should have changed.

Sources

Checked 14 November 2026.

Next

Next: Files, the browser, and memory.

Checked 14 November 2026 · prices, limits, and versions change