When something doesn’t work

AIOS runs local inference through Ollama, which isn’t installed, isn’t running, or has no models pulled — and no BYOK cloud provider key is configured as an alternative.

You have two paths, and you don’t need a GPU to use either. Path A (local): install Ollama, make sure it’s running, and pull a model from the Models tab. Path B (no local model): skip Ollama entirely and connect a cloud provider key (Claude, OpenAI, etc.) in Settings, or use the Claude Code fallback path from onboarding. If you expected Ollama to be detected and it wasn’t, confirm the Ollama service is actually running before retrying — AIOS checks for it, it doesn’t start it for you.

No model is pulled yet, or the model AIOS is trying to route to isn’t installed locally. AIOS also only runs one model in flight at a time (a single-worker VRAM scheduler), so a second request will queue behind the first rather than run in parallel.

Open the Models tab and pull the model(s) your workflow needs — check the tab’s recommendation list if you’re not sure which. If things feel slow under multiple simultaneous requests, that’s expected: only one generation runs against your GPU at a time by design, to avoid over-committing VRAM. Subsequent requests will complete once the current one finishes.

AIOS’s backend is a local Python (FastAPI) sidecar process that the desktop app spawns on startup. If that sidecar fails to launch — most commonly because antivirus/firewall software is blocking it, or another process is already bound to its local port — the frontend has nothing to talk to.

First, just restart the app — transient sidecar startup failures are usually resolved by relaunch. If it persists: check that your antivirus or firewall isn’t quarantining or blocking the AIOS backend process or its local network connection (allow it if prompted). Also check for a port conflict — another application may already be using the local backend port; closing that other application and relaunching AIOS often resolves it. If none of that works, a full reboot clears most lingering port/process locks.

AIOS keeps a system tray icon running by design so the app can be quickly restored, and closing the main window hides it rather than fully quitting. This is intentional, not a bug — but it means “closing the window” isn’t the same as “quitting the app.”

To fully quit AIOS (and its backend), right-click the tray icon and choose Quit, rather than just closing the window. If you suspect a stuck process is preventing a clean restart, quit fully via the tray menu first, then relaunch.

License activation is verified fully offline against a public key baked into the desktop app — it does not phone home, so an internet outage is not the cause of an activation failure. The far more common causes are a copy-paste error in the license token (extra whitespace, a truncated paste, missing characters) or a license that’s genuinely expired or been deactivated on your account.

Re-copy the license token from your account dashboard, taking care to select the whole string, and paste it fresh into AIOS rather than editing a previous paste. If it still fails, log into the account portal and check your license/subscription status directly — if it shows expired or deactivated there, that’s the real cause and needs to be resolved on the billing side (portal dashboard) before the token will verify locally.

This can happen if your license genuinely expired or was deactivated. It is not caused by a network blip — offline verification means AIOS doesn’t need to reach the internet to keep validating an already-activated license.

Check your license status in the account dashboard first. If your subscription is active there but AIOS still shows Free-tier limits, try deactivating and reactivating the license in AIOS with a freshly copied token, following the same copy-paste care as above.

This is intentional, not a malfunction. AIOS meters spend token-by-token during generation and hard-stops the stream the moment it would cross your configured cost cap — a deliberate kill-switch design so you can never blow past your budget mid-generation, rather than a “soft” warning after the fact.

On paid tiers, the cap is configurable — raise it in Settings if you want more headroom for long generations. On the Free tier, the cost cap is fixed and cannot be raised; if you’re consistently hitting it, that’s a signal to either scope your requests smaller or move to a paid tier where the cap is adjustable.

This is a deliberate safety control, not a bug. The Orchestrator bridge only allows dispatch into repo paths that have been explicitly registered with AIOS (an allow-list) — this prevents a dispatched agent from touching arbitrary filesystem locations outside repos you’ve approved.

Check that the repository path you’re targeting is actually registered in AIOS (Settings’ repo paths section, or wherever you manage repos). If it isn’t, register it first, then retry the dispatch. If the path is already registered and dispatch is still rejected, check whether you’ve hit the daily dispatch cap — Free tier is limited to 3 agent dispatches per day; that cap resets after 24 hours, or you can move to a paid tier for a higher/unlimited allowance.

Free tier enforces a daily cap of 3 agent dispatches. Once used up, further dispatch attempts are rejected until the cap resets.

Wait for the daily cap to reset (24 hours from your first dispatch that day), or upgrade to a paid tier for a higher or unlimited daily allowance. This is a tier limit working as intended, not an error condition to debug.

AIOS’s MCP server only runs locally as part of the desktop app — if AIOS isn’t running, there’s nothing to connect to. Beyond that, MCP mode is free on every tier including Free, so a missing license is not the cause of a connection failure. The most client-specific gotcha is Claude Desktop: it only supports stdio-based MCP servers, not a local HTTP server, so it cannot connect to AIOS directly no matter how the port is configured.

First confirm AIOS is actually running (check the tray icon) and that the local port it’s serving on hasn’t changed or been blocked by antivirus/firewall (same check as the sidecar-startup issue above). For Claude Desktop specifically, you must use the mcp-remote bridge in its config to translate stdio to AIOS’s local HTTP endpoint — pointing Claude Desktop’s config directly at the HTTP address will not work, that’s a protocol mismatch, not a bug. Clients that do support HTTP-based MCP servers (Cursor, Codex CLI) can point at the local address directly once AIOS is confirmed running.

Not every issue is covered by a specific troubleshooting entry, and some things that look like bugs (hard cost-cap stops, dispatch rejections, MCP Desktop’s stdio-only limitation) are intentional design decisions rather than defects.

Check the FAQ page first for quick answers to common questions. If your issue looks like an actual defect rather than expected behavior, search the project’s GitHub repository for existing issues before filing a new one — someone may have already hit and documented the same thing. For anything else, use the Contact page to reach the team directly.