# Self-host AutoAIDev — run autonomous AI coding agents on your own machine

AutoAIDev is the **loop**, not the AI. It reads your `TODO.md`, hands each task to an AI provider you already run locally — **Claude**, **Grok**, **Copilot**, or **OpenCode** — edits your files, marks the task `[x]`, and moves on.

There are three ways to self-host it, in order of recommendation:

- **A. CLI** — fastest, any OS.
- **B. VS Code / Cursor extension** — in the editor you already use, any OS.
- **C. Desktop app** — a GUI dashboard for many agents, Linux x86_64.

![The whole self-host loop in one terminal: init, add a task, start, and watch the checkbox flip to done.](../media/cli-selfhost.gif)

*The whole self-host loop in one terminal: `init` → add a task → `start` → watch `[ ]` flip to `[x]`.*

---

## Free & private — your keys, your logs, your code

Self-hosting means the whole loop runs on your box. AutoAIDev talks to whichever AI provider you're already signed into locally, using **your** credentials. There's no AutoAIDev account, no cloud seat, and no upload of your repository to us.

- **Your keys.** The agent uses the provider login already on your machine — nothing is proxied through us.
- **Your logs.** Sessions and traces are written to your workspace, not a remote dashboard.
- **Your box.** The loop and every file edit happen locally. Offline-capable once the provider is set up.
- **Your code.** Your repository is never uploaded to AutoAIDev. Free, MIT-licensed, no lock-in.

Connecting to a shared [Pixel Office](#connect-to-a-pixel-office-optional) later is entirely optional — it's a team view you add *after* a local agent is already working, not a sign-up wall.

---

## Step 0 — give your agent a brain

> This is the single step almost everyone forgets, and skipping it is the No. 1 first-run snag.

AutoAIDev is the loop; it needs a separate AI provider CLI installed **and logged in** to do the actual thinking. These providers are **not bundled**. You only need one. It's the same prerequisite for the CLI, the extension, and the desktop app.

**New here? Install the default provider — Claude Code.** Install it, then run `claude` once to log in through your browser. That single login is what lets every AutoAIDev surface think.

```bash
npm install -g @anthropic-ai/claude-code   # install Claude Code (the "brain")
claude                                      # run once and log in when prompted
```

Prefer another provider? AutoAIDev also drives **Grok**, **GitHub Copilot**, and **OpenCode** — install any one of their CLIs, log in, and select it later with the `-p` flag (e.g. `-p grok`, `-p copilot`, `-p opencode`). You still only need one.

Skip Step 0 and the loop will start but idle or error the moment it needs to think — the classic `TODO empty — polling` or a silent `please login`. Do it once and every surface below just works.

---

## A. Self-host with the CLI (fastest)

The engine is `autodev-cli`. Four moves — install, init, add a task, start — and an agent is draining your `TODO.md` on your own machine. (Do [Step 0](#step-0--give-your-agent-a-brain) first — the loop can't think without it.)

1. **Install** the engine — `npm install -g autodev-cli`.
2. **Init** a folder — `autodev init .` scaffolds `TODO.md` and `.autodev/settings.json`. That folder becomes your agent's workspace.
3. **Add a task** — write `- [ ] make a hello-world Flask app` under the `## Todo` heading in `TODO.md`.
4. **Start** — `autodev start .` picks the first `- [ ]`, dispatches it to your provider, and edits files until it's `[x]`.

```bash
npm install -g autodev-cli          # 1. install the loop engine
mkdir my-agent && cd my-agent       #    a folder = your agent's workspace
autodev init .                      # 2. scaffold TODO.md + .autodev/settings.json
# 3. add "- [ ] make a hello-world Flask app" under the "## Todo" heading in TODO.md
autodev start .                     # 4. run it — watch [ ] flip to [x]
```

Prefer not to install globally? Use `npx autodev-cli`. Want a different provider? Add `-p grok` (or `copilot` / `opencode`) to `autodev start`; the default is Claude.

![Animated terminal: autodev init scaffolds the workspace, a task is added to TODO.md, and autodev start dispatches it to the provider and marks it done.](../media/cli-selfhost.gif)

*The full flow, animated — exactly what your terminal does after the four commands above.*

| `autodev init .` | `autodev start .` |
|---|---|
| ![Terminal screenshot of autodev init scaffolding TODO.md and the .autodev settings folder in a fresh workspace.](../media/cli-init.png) | ![Terminal screenshot of autodev start picking a pending task, dispatching to the provider, and reporting progress.](../media/cli-start.png) |
| **Step 2.** `init` scaffolds `TODO.md` and settings — the folder is now an agent workspace. | **Step 4.** `start` picks the first task, dispatches to your provider, and reports each edit. |

### What the loop actually does

On `start` the loop reads `TODO.md`, picks the first `- [ ]` under `## Todo`, marks it `[~]` in progress, and dispatches it to your provider. The provider edits files in place and, when finished, rewrites the line as `[x] YYYY-MM-DD  text` (two spaces). Completion is detected by the exact line it marked, so rephrasing a task mid-run is safe. Then it advances to the next task; when the list is empty it polls and waits for you to add more.

**Requirements:** Node.js (for `npm`) · at least one provider CLI installed and logged in from [Step 0](#step-0--give-your-agent-a-brain) · a folder you're happy for the agent to edit.

### Troubleshooter

- **It said "please login"** — the provider isn't authenticated. Run `claude` (or your provider's CLI) once and log in. That's Step 0.
- **Nothing happened / "TODO empty"** — your task isn't under the `## Todo` heading, or it's not a `- [ ]` checkbox. Add one real task and save.
- **It paused for a while** — a provider rate-limit resets the task to `[ ]` and pauses the loop until the reset time. It resumes on its own.

---

## B. Self-host in VS Code or Cursor

Same engine, run from a sidebar in the editor you already use. Works on Windows, macOS, and Linux — the safest first step if you'd rather not touch the terminal. It still needs [Step 0](#step-0--give-your-agent-a-brain): a provider CLI installed and logged in.

1. **Install** — open the Extensions panel (`Ctrl+Shift+X`), search **AutoAIDev**, click **Install**. Or grab the `.vsix` (below).
2. **Open the AutoDev sidebar** — the AutoAIDev icon appears in the activity bar; click it for the Tasks / Settings / Profile panels.
3. **Step 0 check** — pick your provider in the dropdown; make sure that provider CLI is installed and logged in.
4. **Add tasks & Start** — write `- [ ]` tasks in the panel (or in `TODO.md`) and hit **Start**. Watch live tool activity.

One-line install from the VSIX (works for both VS Code and Cursor):

```bash
curl -L -o autoaidev.vsix "https://autoaidev.com/releases/autoaidev-latest.vsix" && code --install-extension autoaidev.vsix
```

- Marketplace: <https://marketplace.visualstudio.com/items?itemName=AutoAIDev.autoaidev>
- Direct `.vsix`: <https://autoaidev.com/releases/autoaidev-latest.vsix>

**Requirements:** VS Code **1.99+** (or Cursor) · a provider CLI installed and logged in ([Step 0](#step-0--give-your-agent-a-brain)) · on Linux, `xdotool` for keyboard automation.

---

## C. Self-host with the desktop app

A GUI that runs and watches many agents at once — no terminal needed. Ships as a Linux x86_64 **AppImage**. Same [Step 0](#step-0--give-your-agent-a-brain) provider prerequisite applies.

1. **Download** the AppImage (Linux x64) from the link below.
2. **Make it runnable** — `chmod +x AutoAIDev-desktop-latest.AppImage`, then double-click or run it.
3. **Pick a folder** — that folder becomes an agent's workspace. Choose your provider (Step 0).
4. **Start** — hit Start and manage many agents from the dashboard: per-agent chat, live output, sessions.

```bash
curl -L -o AutoAIDev-desktop-latest.AppImage "https://autoaidev.com/releases/AutoAIDev-desktop-latest.AppImage"
chmod +x AutoAIDev-desktop-latest.AppImage   # make it executable
./AutoAIDev-desktop-latest.AppImage          # launch — then pick a folder & Start
```

- Download: <https://autoaidev.com/releases/AutoAIDev-desktop-latest.AppImage>
- `autodev-app` on npm: <https://www.npmjs.com/package/autodev-app>

![The AutoAIDev desktop app managing many autonomous agents at once: a dashboard of agent cards with live status, output, and per-agent controls.](../media/epicmovies-app.png)

*What you get: one window running and watching many agents — dashboard, per-agent chat/steer, live output, and a sessions browser.*

**Requirements:** Linux x86_64 · a provider CLI installed and logged in ([Step 0](#step-0--give-your-agent-a-brain)). Not yet available for Windows or macOS — use the [VS Code / Cursor extension](#b-self-host-in-vs-code-or-cursor) there instead (same engine).

---

## Connect to a Pixel Office (optional)

This is the *second* thing you do, not the first. Once a local agent is already running, you can connect it to a shared **Pixel Office** — a web view where your local agent shows up as a live character your team can watch, chat with, and steer. It stays running on your machine; the office is just a window into it.

![A pixel-art web office with multiple AI agents rendered as characters moving around desks and rooms.](../media/pixel-office-fullhouse.png)

*The payoff: your locally-running agents appear as characters in a shared office view.*

![Chatting with and steering an AI agent inside the pixel office: a chat panel beside the agent's character with live messages.](../media/pixel-office-chat.png)

*Talk to it: message a running agent to steer it mid-task, right from the office.*

Connecting is optional and comes *after* a working local agent — it does not replace self-hosting. You bind an existing agent to an office with `autodev connect` (or the Connect option in the desktop app). Your keys and code still stay on your machine.

---

*AutoAIDev is MIT-licensed. Self-host — your machine, your keys, your code.*