Documentation

Docs & Setup Guide

Everything you need to install ARIA OS, connect your AI model and tools, and keep it up to date.

Your operating system

Steps that differ by OS update automatically. Shared topics (API keys, Forge, the apps) apply to all.

Quick start

ARIA OS is a private AI desktop that runs on your machine and uses the AI model you choose. Fastest path:

  1. Download the build for your OS from the Download page (Windows, macOS, or Linux).
  2. Install/open it (per-OS steps below), then create your account or log in.
  3. Connect a model: paste your own API key, or use your local Claude Code / Codex CLI login.
  4. Start chatting with Aria — and hand build tasks to the Forge agent.

Use the Windows / macOS / Linux switcher above — the install, update, command, and troubleshooting steps update to match your system.

Installing ARIA OSWindows

Download the installer from the Download page (the "Download for Windows" button). Windows 10 & 11, 64-bit.

  1. Run the file you downloaded (ARIA-OS-Setup.exe).
  2. If a blue "Windows protected your PC" notice appears, click "More info", then "Run anyway". Windows shows this for any app installed directly from the web rather than the Microsoft Store — it is expected during the beta and the app is safe (see Troubleshooting for details).
  3. When it finishes, open ARIA OS from the Start menu or the desktop shortcut.

System requirements

  • Windows 10 or 11, 64-bit.
  • 8 GB RAM minimum, 16 GB recommended.
  • About 500 MB of disk + room for your local cache.
  • Online for sync and AI; core work runs locally.

Your account & signing in

On first open, create an account with your email and a password, or sign in. Your private workspace is created automatically — no server, Docker, or config files.

Your account keeps everything in sync across the desktop app, the web, and connected surfaces like Telegram. Sign in with the same account everywhere to see the same chats, memory, and settings.

Connecting your AI model (API keys)

ARIA OS runs on the model you choose, and you bring your own access — no token markup. Two options.

You do NOT need the Claude or Codex CLI. The simplest setup is just an API key (Option A) — ARIA OS has a built-in Forge build engine, so Aria can chat and build with only a key. The CLIs (Option B) are optional; to use them with your own key, see the command section below.

Option A — Bring your own API key

Get a key from your provider, then add it in the app under Settings → API Keys: pick the provider, paste your key, choose a model.

Option B — Use your local CLI (no API key)

If you already have the Claude Code CLI or Codex CLI installed and logged in, choose Claude (local) or Codex (local) in Settings → API Keys — ARIA OS uses your existing CLI login.

Run the Claude or Codex CLI with your own API keyWindows

You do NOT need the Claude or Codex CLI — an API key is enough (see above). But if you prefer those CLIs, run them with your OWN pay-as-you-go key instead of a paid subscription. These are Windows PowerShell commands.

Claude Code CLI with your own Anthropic key

npm install -g @anthropic-ai/claude-code
setx ANTHROPIC_API_KEY "sk-ant-your-key"
# open a NEW terminal, then:
claude

Claude Code CLI with OpenRouter (any provider)

Point Claude Code at OpenRouter so one key gives it many models (ANTHROPIC_API_KEY must be empty):

setx ANTHROPIC_BASE_URL "https://openrouter.ai/api"
setx ANTHROPIC_AUTH_TOKEN "sk-or-your-key"
setx ANTHROPIC_API_KEY ""
setx ANTHROPIC_MODEL "anthropic/claude-sonnet-4"
# new terminal, then run:  claude

Codex CLI with your own OpenAI key

npm install -g @openai/codex
setx OPENAI_API_KEY "sk-your-key"
# new terminal, then run:  codex

Codex CLI with OpenRouter

Create C:\Users\<your-username>\.codex\config.toml with:

model_provider = "openrouter"
model = "openai/gpt-4o"   # any model id from openrouter.ai/models

[model_providers.openrouter]
name = "OpenRouter"
base_url = "https://openrouter.ai/api/v1"
env_key = "OPENROUTER_API_KEY"
wire_api = "responses"
setx OPENROUTER_API_KEY "sk-or-your-key"
# new terminal, then run:  codex

Get keys: console.anthropic.com, platform.openai.com/api-keys, openrouter.ai/keys.

Meet Aria — chat & memory

Aria is your assistant — a real window that remembers your projects, people, and preferences across conversations, and can actually do things, not just talk back.

Memory is shared: what you tell Aria on the desktop is available on the web and over Telegram, and vice versa. The more you use her, the more context she carries.

Forge — the build agent

Forge is ARIA OS’s execution agent. Hand it a task in plain language ("build me a Python script that…", "clean up this folder and email me a summary") and it writes code, edits files, and runs commands in your workspace. ARIA OS includes a built-in Forge engine, so this works without any external CLI.

Permission modes

  • Safe — inspects and proposes, never changes anything.
  • Ask — does normal work, prompts before anything risky.
  • Autonomous — runs freely in workspaces you trust; the safety rails never turn off.
Nothing is "done" without a logged, auditable record — no silent edits. Grant autonomy on machines and projects you trust, and review what it runs.

The apps

ARIA OS is a full desktop where each capability is its own app, all sharing the same assistant and memory. From the dock:

  • Files — browse and act on your local files.
  • Terminal — a real terminal in the OS.
  • Browser — a built-in web browser.
  • Mail — read and draft email.
  • Notes, Tasks, Calendar, Reminders — synced and backed up.
  • Knowledge — point ARIA at a folder to index it into memory.
  • People — keep profiles of people you know.
  • Agents — install and launch additional agents.
  • Activity Monitor & Logs — see what is running and what happened.

GitHub backup — your memory in your repo

ARIA OS can back up your memory and chat history to a private GitHub repository you own — not a vendor black box. Read, export, or delete it anytime.

  1. Create a GitHub access token at github.com/settings/tokens with permission to create + write repositories (fine-grained Contents: read/write, or a classic token with the "repo" scope). Copy it.
  2. In ARIA OS open Settings → Backup, paste the token, and connect.
  3. ARIA OS creates a PRIVATE repo and mirrors your workspace, memory, and chats automatically — roughly every 20 minutes and on quit.
Because your backup lives in your own private repo, your data stays portable and yours — and it survives app updates.

Connect Telegram (chat from your phone)

Connect a Telegram bot and chat with Aria from your phone — always-on. She answers whether or not your desktop is open; tasks that need your computer run on your desktop when it is online.

  1. In Telegram, message @BotFather and send /newbot, follow the prompts, copy the bot token.
  2. In ARIA OS open Settings → Connections → Telegram, paste the token, enable it.
  3. Message your bot to start chatting with Aria.

Setting up Mail

Connect your email so Aria can read and draft messages. In Settings (Mail / Connections), connect with your email address and an app password.

For Gmail or Outlook, create an app-specific password in your account’s security settings and use that instead of your normal password. ARIA OS connects over IMAP/SMTP and stores credentials encrypted.

Screen vision (the eye)

Click the eye button in chat to let Aria see your screen and answer questions about it. This needs a vision-capable model (a Claude or GPT model that supports images, or your local CLI). The capture happens on your machine, so keep the desktop app open.

Writing Tools everywhere

Select text in almost any app to proofread, rewrite, change tone, or summarize it where you are — via the right-click menu (Writing Tools) or Ctrl/Cmd+Shift+W.

Plans, limits & billing

Three plans. Your model usage is billed by your own provider; the plan pays for the product.

  • Free — 50 messages + 100 tool-actions / month (new accounts get a boosted 200 + 200 for the first month).
  • Pro ($20/mo) — 3,000 messages + 3,000 tool-actions / month.
  • Max ($50/mo) — unlimited messages and tool-actions.

Manage your plan in Settings → Billing. Payments are processed securely by Stripe; cancel anytime and keep access through the period you paid for. See the Refund & Cancellation Policy.

Updating ARIA OSWindows

ARIA OS does not auto-update. When a new version is out you will see an in-app notice — but you install it yourself from the website. This keeps updates reliable and never interrupts your work.

  1. Fully quit ARIA OS — close the window AND quit it from the system tray, so nothing is still running.
  2. Download the latest installer from the Download page.
  3. Recommended: uninstall the previous version first — Windows Settings → Apps → ARIA OS → Uninstall. This does NOT delete your data.
  4. Run the installer you downloaded, then open ARIA OS.
Why uninstall first? Installing over a running or locked previous version can stall with "ARIA OS cannot be closed". Uninstalling first avoids that — and your account, settings, and data are preserved across the reinstall.

Privacy & your data

ARIA OS is local-first. The desktop does its work on your machine, your files stay local, and your model keys/credentials are encrypted and never returned to the browser. Your memory backs up to a private GitHub repo you own.

Full details: our Privacy Policy and Security pages.

TroubleshootingWindows

"Windows protected your PC" when installing

Windows SmartScreen shows this for apps installed directly from the web rather than the Microsoft Store, which is how the beta is distributed. Click "More info" → "Run anyway". It is safe to install.

An update will not apply / "ARIA OS cannot be closed"

Make sure ARIA OS is fully closed (including the system-tray icon), then run the installer again. If it still will not replace the old version, uninstall the previous version first (your data is preserved) and then install the new one.

"Claude CLI not found" or a local model is not responding

Local-model and some agent actions run on your desktop — keep the app open and online, and make sure your Claude Code / Codex CLI is installed and logged in. Or just add an API key in Settings → API Keys.

Forge is not building anything

Confirm you set an API key (or are logged into a local CLI) and picked a model in Settings → API Keys.

Still stuck?

Email us at ar.dev@anshulraman.com — see the Contact page.